diff options
Diffstat (limited to 'docs/html/guide/topics')
| -rw-r--r-- | docs/html/guide/topics/connectivity/bluetooth-le.jd | 608 | ||||
| -rw-r--r-- | docs/html/guide/topics/connectivity/bluetooth.jd | 43 | ||||
| -rw-r--r-- | docs/html/guide/topics/graphics/hardware-accel.jd | 518 | ||||
| -rw-r--r-- | docs/html/guide/topics/graphics/opengl.jd | 414 | ||||
| -rw-r--r-- | docs/html/guide/topics/graphics/renderscript/graphics.jd | 994 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/activity-element.jd | 521 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/application-element.jd | 89 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/uses-sdk-element.jd | 12 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/advanced.jd | 158 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/compute.jd | 528 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/index.jd | 20 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/drawable-resource.jd | 7 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/actionbar.jd | 1675 |
13 files changed, 2774 insertions, 2813 deletions
diff --git a/docs/html/guide/topics/connectivity/bluetooth-le.jd b/docs/html/guide/topics/connectivity/bluetooth-le.jd new file mode 100644 index 0000000..21950c2 --- /dev/null +++ b/docs/html/guide/topics/connectivity/bluetooth-le.jd @@ -0,0 +1,608 @@ +page.title=Bluetooth Low Energy +page.tags="wireless","bluetoothadapter","bluetoothdevice","BLE","BTLE" +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#terms">Key Terms and Concepts</a> + <ol> + <li><a href="#roles">Roles and Responsibilities</a></li> + </ol> + </li> + <li><a href="#permissions">BLE Permissions</a></li> + <li><a href="#setup">Setting Up BLE</a></li> + <li><a href="#find">Finding BLE Devices</a></li> + <li><a href="#connect">Connecting to a GATT Server</a></li> + <li><a href="#read">Reading BLE Attributes</a></li> + <li><a href="#notification">Receiving GATT Notifications</a></li> + <li><a href="#close">Closing the Client App</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.bluetooth.BluetoothGatt}</li> + <li>{@link android.bluetooth.BluetoothGattCallback}</li> + <li>{@link android.bluetooth.BluetoothGattCharacteristic}</li> + <li>{@link android.bluetooth.BluetoothGattService}</li> + </ol> + + <h2>Related samples</h2> + <ol> + <li><a href="{@docRoot}tools/samples/index.html">Bluetooth LE sample</a></li> + </ol> + + <h2>See Also</h2> + <ol> + <li><a href="http://developers.google.com/events/io/sessions/326240948"> + Best Practices for Bluetooth Development</a> (video)</li> + + </ol> + +</div> +</div> + + +<p> +Android 4.3 (API Level 18) introduces built-in platform support for Bluetooth Low +Energy in the <em>central role</em> and provides APIs that apps can use to discover +devices, query for services, and read/write characteristics. +In contrast to +<a href="{@docRoot}guide/topics/connectivity/bluetooth.html">Classic Bluetooth</a>, +Bluetooth Low Energy (BLE) is designed to provide significantly lower power consumption. +This allows Android apps to communicate with BLE devices that have low power requirements, +such as proximity sensors, heart rate monitors, fitness devices, and so on.</p> + +<h2 id="terms">Key Terms and Concepts</h2> +<p>Here is a summary of key BLE terms and concepts:</p> +<ul> + <li><strong>Generic Attribute Profile (GATT)</strong>—The GATT profile +is a general specification for sending and receiving short pieces of data known +as "attributes" over a BLE link. All current Low Energy application profiles are +based on GATT. + <ul> + <li>The Bluetooth SIG defines many +<a href="https://www.bluetooth.org/en-us/specification/adopted-specifications">profiles</a> +for Low Energy devices. A profile is a specification for how a device works in a +particular application. Note that a device can implement more than one profile. +For example, a device could contain a heart rate monitor and a battery level +detector.</li> + </ul> + </li> + <li><strong>Attribute Protocol (ATT)</strong>—GATT is built on top of +the Attribute Protocol (ATT). This is also referred to as GATT/ATT. ATT is +optimized to run on BLE devices. To this end, it uses as few bytes as possible. +Each attribute is uniquely identified by a Universally Unique Identifier (UUID), +which is a standardized 128-bit format for a string ID used to uniquely +identify information. The <em>attributes</em> transported by ATT are formatted +as <em>characteristics</em> and <em>services</em>. </li> + + <li><strong>Characteristic</strong>—A characteristic contains a single +value and 0-n descriptors that describe the characteristic's value. A +characteristic can be thought of as a type, analogous to a class. </li> + <li><strong>Descriptor</strong>—Descriptors are defined attributes that +describe a characteristic value. For example, a descriptor might specify a +human-readable description, an acceptable range for a characteristic's value, or +a unit of measure that is specific to a characteristic's value.</li> + + <li><strong>Service</strong>—A service is a collection of +characteristics. For example, you could have a service called +"Heart Rate Monitor" that includes characteristics such as +"heart rate measurement." You can find a list of existing GATT-based +profiles and services on +<a href="https://www.bluetooth.org/en-us/specification/adopted-specifications"> +bluetooth.org</a>.</li> + +</ul> + +<h3 id="roles">Roles and Responsibilities</h3> + +<p>Here are the roles and responsibilities that apply when +an Android device interacts with a BLE device:</p> + +<ul> + <li>Central vs. peripheral. This applies to the BLE connection itself. The + device in the central role scans, looking for advertisement, and the device in + the peripheral role makes the advertisement.</li> + <li>GATT server vs. GATT client. This determines how two devices talk to each +other once they've established the connection.</li> +</ul> + +<p>To understand the distinction, imagine that you have an Android phone and +an activity tracker that is a BLE device. The phone supports the +central role; the activity tracker supports the peripheral role (to +establish a BLE connection you need one of each—two things that only support +peripheral couldn't talk to each other, nor could two things that only support +central).</p> + +<p>Once the phone and the activity tracker have established a connection, they +start transferring GATT metadata to one another. Depending on the kind of data they transfer, +one or the other might act as the server. For example, if the activity tracker +wants to report sensor data to the phone, it might make sense for the activity +tracker to act as the server. If the activity tracker wants to receive updates +from the phone, then it might make sense for the phone to act +as the server.</p> + +<p> +In the example used in this document, the Android app (running on an Android +device) is the GATT client. The app gets data from the GATT server, which is a +BLE heart rate monitor that supports the +<a href="http://developer.bluetooth.org/TechnologyOverview/Pages/HRP.aspx">Heart +Rate Profile</a>. But you could alternatively design +your Android app to play the GATT server +role. See {@link android.bluetooth.BluetoothGattServer} for more +information.</p> + +<h2 id="permissions">BLE Permissions</h2> + +<p>In order to use Bluetooth features in your application, you must declare +the Bluetooth permission {@link android.Manifest.permission#BLUETOOTH}. +You need this permission to perform any Bluetooth communication, +such as requesting a connection, accepting a connection, and transferring data.</p> + +<p>If you want your app to initiate device discovery or manipulate Bluetooth +settings, you must also declare the {@link android.Manifest.permission#BLUETOOTH_ADMIN} +permission. <strong>Note:</strong> If you use the +{@link android.Manifest.permission#BLUETOOTH_ADMIN} permission, then you must +also have the {@link android.Manifest.permission#BLUETOOTH} permission.</p> + +<p>Declare the Bluetooth permission(s) in your application manifest file. For +example:</p> + +<pre> +<uses-permission android:name="android.permission.BLUETOOTH"/> +<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/></pre> + +<p>If you want to declare that your app is available to BLE-capable devices only, +include the following in your app's manifest:</p> + +<pre><uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/> +</pre> + +<p>However, if you want to make your app available to devices that don't support BLE, +you should still include this element in your app's manifest, but set {@code required="false"}. +Then at run-time you can determine BLE availability by using +{@link android.content.pm.PackageManager#hasSystemFeature PackageManager.hasSystemFeature()}: + +<pre>// Use this check to determine whether BLE is supported on the device. Then +// you can selectively disable BLE-related features. +if (!getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)) { + Toast.makeText(this, R.string.ble_not_supported, Toast.LENGTH_SHORT).show(); + finish(); +}</pre> + +<h2 id="setup">Setting Up BLE</h2> + +<p>Before your application can communicate over BLE, you need +to verify that BLE is supported on the device, and if so, ensure that it is enabled. +Note that this check is only necessary if {@code <uses-feature.../>} +is set to false.</p> + +<p>If BLE is not supported, then you should gracefully disable any +BLE features. If BLE is supported, but disabled, then you can request that the +user enable Bluetooth without leaving your application. This setup is +accomplished in two steps, using the {@link android.bluetooth.BluetoothAdapter}. +</p> + + +<ol> +<li>Get the {@link android.bluetooth.BluetoothAdapter} +<p>The {@link android.bluetooth.BluetoothAdapter} is required for any and all +Bluetooth activity. The {@link android.bluetooth.BluetoothAdapter} represents +the device's own Bluetooth adapter (the Bluetooth radio). There's one Bluetooth +adapter for the entire system, and your application can interact with it using +this object. The snippet below shows how to get the adapter. Note that this approach +uses {@link android.content.Context#getSystemService getSystemService()} to return +an instance of {@link android.bluetooth.BluetoothManager}, which is then +used to get the adapter. Android 4.3 (API Level 18) introduces +{@link android.bluetooth.BluetoothManager}:</p> + +<pre>// Initializes Bluetooth adapter. +final BluetoothManager bluetoothManager = + (BluetoothManager) getSystemService(Context.BLUETOOTH_SERVICE); +mBluetoothAdapter = bluetoothManager.getAdapter(); +</pre> +</li> + +<li>Enable Bluetooth +<p>Next, you need to ensure that Bluetooth is enabled. Call {@link +android.bluetooth.BluetoothAdapter#isEnabled()} to check whether Bluetooth is +currently enabled. If this method returns false, then Bluetooth is disabled. +The following snippet checks whether Bluetooth is enabled. If it isn't, the +snippet displays an error prompting the user to go to Settings to enable +Bluetooth:</p> +<pre>private BluetoothAdapter mBluetoothAdapter; +... +// Ensures Bluetooth is available on the device and it is enabled. If not, +// displays a dialog requesting user permission to enable Bluetooth. +if (mBluetoothAdapter == null || !mBluetoothAdapter.isEnabled()) { + Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE); + startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT); +} +</li> +</ol> + + + +<h2 id="find">Finding BLE Devices</h2> + +<p>To find BLE devices, you use the +{@link android.bluetooth.BluetoothAdapter#startLeScan startLeScan()} method. +This method takes a {@link android.bluetooth.BluetoothAdapter.LeScanCallback} +as a parameter. You must implement this callback, because that is how scan +results are returned. Because scanning is battery-intensive, you should observe +the following guidelines:</p> +<ul> + <li>As soon as you find the desired device, stop scanning.</li> + <li>Never scan on a loop, and set a time limit on your scan. A device that was +previously available may have moved out of range, and continuing to scan drains +the battery.</li> +</ul> + +<p>The following snippet shows how to start and stop a scan:</p> + +<pre>/** + * Activity for scanning and displaying available BLE devices. + */ +public class DeviceScanActivity extends ListActivity { + + private BluetoothAdapter mBluetoothAdapter; + private boolean mScanning; + private Handler mHandler; + + // Stops scanning after 10 seconds. + private static final long SCAN_PERIOD = 10000; + ... + private void scanLeDevice(final boolean enable) { + if (enable) { + // Stops scanning after a pre-defined scan period. + mHandler.postDelayed(new Runnable() { + @Override + public void run() { + mScanning = false; + mBluetoothAdapter.stopLeScan(mLeScanCallback); + } + }, SCAN_PERIOD); + + mScanning = true; + mBluetoothAdapter.startLeScan(mLeScanCallback); + } else { + mScanning = false; + mBluetoothAdapter.stopLeScan(mLeScanCallback); + } + ... + } +... +} +</pre> + +<p>If you want to scan for only specific types of peripherals, you can instead +call {@link android.bluetooth.BluetoothAdapter#startLeScan startLeScan(UUID[], BluetoothAdapter.LeScanCallback)}, +providing an array of {@link java.util.UUID} objects that specify the GATT +services your app supports.</p> + +<p>Here is an implementation of the +{@link android.bluetooth.BluetoothAdapter.LeScanCallback}, +which is the interface used to deliver BLE scan results:</p> + +<pre> +private LeDeviceListAdapter mLeDeviceListAdapter; +... +// Device scan callback. +private BluetoothAdapter.LeScanCallback mLeScanCallback = + new BluetoothAdapter.LeScanCallback() { + @Override + public void onLeScan(final BluetoothDevice device, int rssi, + byte[] scanRecord) { + runOnUiThread(new Runnable() { + @Override + public void run() { + mLeDeviceListAdapter.addDevice(device); + mLeDeviceListAdapter.notifyDataSetChanged(); + } + }); + } +};</pre> + + +<p class="note"><strong>Note:</strong> You can only scan for Bluetooth LE devices +<em>or</em> scan for Classic Bluetooth devices, as described in +<a href="{@docRoot}guide/topics/connectivity/bluetooth.html">Bluetooth</a>. You cannot +scan for both Bluetooth LE and classic devices at the same time.</p> + +<h2 id="connect">Connecting to a GATT Server</h2> + +<p>The first step in interacting with a BLE device is connecting to it— +more specifically, connecting to the GATT server on the device. To +connect to a GATT server on a BLE device, you use the +{@link android.bluetooth.BluetoothDevice#connectGatt connectGatt()} method. +This method takes three parameters: a {@link android.content.Context} object, +<code>autoConnect</code> (boolean indicating whether to automatically connect to +the BLE device as soon as it becomes available), and a reference to a +{@link android.bluetooth.BluetoothGattCallback}: </p> + +<pre>mBluetoothGatt = device.connectGatt(this, false, mGattCallback);</pre> + +<p>This connects to the GATT server hosted by the BLE device, and returns a +{@link android.bluetooth.BluetoothGatt} instance, which you can then use to +conduct GATT client operations. The caller (the Android app) is the GATT client. +The {@link android.bluetooth.BluetoothGattCallback} is used to deliver results +to the client, such as connection status, as well as any further GATT client +operations.</p> + +<p>In this example, the BLE app provides an activity +(<code>DeviceControlActivity</code>) to connect, +display data, and display GATT services and characteristics +supported by the device. Based on user input, this activity communicates with a +{@link android.app.Service} called {@code BluetoothLeService}, +which interacts with the BLE device via the Android BLE API:</p> + +<pre> +// A service that interacts with the BLE device via the Android BLE API. +public class BluetoothLeService extends Service { + private final static String TAG = BluetoothLeService.class.getSimpleName(); + + private BluetoothManager mBluetoothManager; + private BluetoothAdapter mBluetoothAdapter; + private String mBluetoothDeviceAddress; + private BluetoothGatt mBluetoothGatt; + private int mConnectionState = STATE_DISCONNECTED; + + private static final int STATE_DISCONNECTED = 0; + private static final int STATE_CONNECTING = 1; + private static final int STATE_CONNECTED = 2; + + public final static String ACTION_GATT_CONNECTED = + "com.example.bluetooth.le.ACTION_GATT_CONNECTED"; + public final static String ACTION_GATT_DISCONNECTED = + "com.example.bluetooth.le.ACTION_GATT_DISCONNECTED"; + public final static String ACTION_GATT_SERVICES_DISCOVERED = + "com.example.bluetooth.le.ACTION_GATT_SERVICES_DISCOVERED"; + public final static String ACTION_DATA_AVAILABLE = + "com.example.bluetooth.le.ACTION_DATA_AVAILABLE"; + public final static String EXTRA_DATA = + "com.example.bluetooth.le.EXTRA_DATA"; + + public final static UUID UUID_HEART_RATE_MEASUREMENT = + UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT); + + // Various callback methods defined by the BLE API. + private final BluetoothGattCallback mGattCallback = + new BluetoothGattCallback() { + @Override + public void onConnectionStateChange(BluetoothGatt gatt, int status, + int newState) { + String intentAction; + if (newState == BluetoothProfile.STATE_CONNECTED) { + intentAction = ACTION_GATT_CONNECTED; + mConnectionState = STATE_CONNECTED; + broadcastUpdate(intentAction); + Log.i(TAG, "Connected to GATT server."); + Log.i(TAG, "Attempting to start service discovery:" + + mBluetoothGatt.discoverServices()); + + } else if (newState == BluetoothProfile.STATE_DISCONNECTED) { + intentAction = ACTION_GATT_DISCONNECTED; + mConnectionState = STATE_DISCONNECTED; + Log.i(TAG, "Disconnected from GATT server."); + broadcastUpdate(intentAction); + } + } + + @Override + // New services discovered + public void onServicesDiscovered(BluetoothGatt gatt, int status) { + if (status == BluetoothGatt.GATT_SUCCESS) { + broadcastUpdate(ACTION_GATT_SERVICES_DISCOVERED); + } else { + Log.w(TAG, "onServicesDiscovered received: " + status); + } + } + + @Override + // Result of a characteristic read operation + public void onCharacteristicRead(BluetoothGatt gatt, + BluetoothGattCharacteristic characteristic, + int status) { + if (status == BluetoothGatt.GATT_SUCCESS) { + broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic); + } + } + ... + }; +... +}</pre> + +<p>When a particular callback is triggered, it calls the appropriate +{@code broadcastUpdate()} helper method and passes it an action. Note that the data +parsing in this section is performed in accordance with the Bluetooth Heart Rate +Measurement +<a href="http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.heart_rate_measurement.xml"> +profile specifications</a>:</p> + +<pre>private void broadcastUpdate(final String action) { + final Intent intent = new Intent(action); + sendBroadcast(intent); +} + +private void broadcastUpdate(final String action, + final BluetoothGattCharacteristic characteristic) { + final Intent intent = new Intent(action); + + // This is special handling for the Heart Rate Measurement profile. Data + // parsing is carried out as per profile specifications. + if (UUID_HEART_RATE_MEASUREMENT.equals(characteristic.getUuid())) { + int flag = characteristic.getProperties(); + int format = -1; + if ((flag & 0x01) != 0) { + format = BluetoothGattCharacteristic.FORMAT_UINT16; + Log.d(TAG, "Heart rate format UINT16."); + } else { + format = BluetoothGattCharacteristic.FORMAT_UINT8; + Log.d(TAG, "Heart rate format UINT8."); + } + final int heartRate = characteristic.getIntValue(format, 1); + Log.d(TAG, String.format("Received heart rate: %d", heartRate)); + intent.putExtra(EXTRA_DATA, String.valueOf(heartRate)); + } else { + // For all other profiles, writes the data formatted in HEX. + final byte[] data = characteristic.getValue(); + if (data != null && data.length > 0) { + final StringBuilder stringBuilder = new StringBuilder(data.length); + for(byte byteChar : data) + stringBuilder.append(String.format("%02X ", byteChar)); + intent.putExtra(EXTRA_DATA, new String(data) + "\n" + + stringBuilder.toString()); + } + } + sendBroadcast(intent); +}</pre> + + + +<p>Back in <code>DeviceControlActivity</code>, these events are handled by a +{@link android.content.BroadcastReceiver}:</p> + +<pre>// Handles various events fired by the Service. +// ACTION_GATT_CONNECTED: connected to a GATT server. +// ACTION_GATT_DISCONNECTED: disconnected from a GATT server. +// ACTION_GATT_SERVICES_DISCOVERED: discovered GATT services. +// ACTION_DATA_AVAILABLE: received data from the device. This can be a +// result of read or notification operations. +private final BroadcastReceiver mGattUpdateReceiver = new BroadcastReceiver() { + @Override + public void onReceive(Context context, Intent intent) { + final String action = intent.getAction(); + if (BluetoothLeService.ACTION_GATT_CONNECTED.equals(action)) { + mConnected = true; + updateConnectionState(R.string.connected); + invalidateOptionsMenu(); + } else if (BluetoothLeService.ACTION_GATT_DISCONNECTED.equals(action)) { + mConnected = false; + updateConnectionState(R.string.disconnected); + invalidateOptionsMenu(); + clearUI(); + } else if (BluetoothLeService. + ACTION_GATT_SERVICES_DISCOVERED.equals(action)) { + // Show all the supported services and characteristics on the + // user interface. + displayGattServices(mBluetoothLeService.getSupportedGattServices()); + } else if (BluetoothLeService.ACTION_DATA_AVAILABLE.equals(action)) { + displayData(intent.getStringExtra(BluetoothLeService.EXTRA_DATA)); + } + } +}; +</pre> + +<h2 id="read">Reading BLE Attributes</h2> + +<p>Once your Android app has connected to a GATT server and discovered services, +it can read and write attributes, where supported. For example, this snippet iterates +through the server's services and characteristics and displays them in the UI:</p> + +<pre> +public class DeviceControlActivity extends Activity { + ... + // Demonstrates how to iterate through the supported GATT + // Services/Characteristics. + // In this sample, we populate the data structure that is bound to the + // ExpandableListView on the UI. + private void displayGattServices(List<BluetoothGattService> gattServices) { + if (gattServices == null) return; + String uuid = null; + String unknownServiceString = getResources(). + getString(R.string.unknown_service); + String unknownCharaString = getResources(). + getString(R.string.unknown_characteristic); + ArrayList<HashMap<String, String>> gattServiceData = + new ArrayList<HashMap<String, String>>(); + ArrayList<ArrayList<HashMap<String, String>>> gattCharacteristicData + = new ArrayList<ArrayList<HashMap<String, String>>>(); + mGattCharacteristics = + new ArrayList<ArrayList<BluetoothGattCharacteristic>>(); + + // Loops through available GATT Services. + for (BluetoothGattService gattService : gattServices) { + HashMap<String, String> currentServiceData = + new HashMap<String, String>(); + uuid = gattService.getUuid().toString(); + currentServiceData.put( + LIST_NAME, SampleGattAttributes. + lookup(uuid, unknownServiceString)); + currentServiceData.put(LIST_UUID, uuid); + gattServiceData.add(currentServiceData); + + ArrayList<HashMap<String, String>> gattCharacteristicGroupData = + new ArrayList<HashMap<String, String>>(); + List<BluetoothGattCharacteristic> gattCharacteristics = + gattService.getCharacteristics(); + ArrayList<BluetoothGattCharacteristic> charas = + new ArrayList<BluetoothGattCharacteristic>(); + // Loops through available Characteristics. + for (BluetoothGattCharacteristic gattCharacteristic : + gattCharacteristics) { + charas.add(gattCharacteristic); + HashMap<String, String> currentCharaData = + new HashMap<String, String>(); + uuid = gattCharacteristic.getUuid().toString(); + currentCharaData.put( + LIST_NAME, SampleGattAttributes.lookup(uuid, + unknownCharaString)); + currentCharaData.put(LIST_UUID, uuid); + gattCharacteristicGroupData.add(currentCharaData); + } + mGattCharacteristics.add(charas); + gattCharacteristicData.add(gattCharacteristicGroupData); + } + ... + } +... +}</pre> + +<h2 id="notification">Receiving GATT Notifications</h2> + +<p>It's common for BLE apps to ask to be notified when a particular +characteristic changes on the device. This snippet shows how to set a notification +for a characteristic, using the +{@link android.bluetooth.BluetoothGatt#setCharacteristicNotification setCharacteristicNotification()} +method:</p> + +<pre> +private BluetoothGatt mBluetoothGatt; +BluetoothGattCharacteristic characteristic; +boolean enabled; +... +mBluetoothGatt.setCharacteristicNotification(characteristic, enabled); +... +BluetoothGattDescriptor descriptor = characteristic.getDescriptor( + UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG)); +descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE); +mBluetoothGatt.writeDescriptor(descriptor);</pre> + +<p>Once notifications are enabled for a characteristic, +an {@link android.bluetooth.BluetoothGattCallback#onCharacteristicChanged onCharacteristicChanged()} +callback is triggered if the characteristic changes on the remote device:</p> + +<pre>@Override +// Characteristic notification +public void onCharacteristicChanged(BluetoothGatt gatt, + BluetoothGattCharacteristic characteristic) { + broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic); +} +</pre> + +<h2 id="close">Closing the Client App</h2> + +<p>Once your app has finished using a BLE device, it should call +{@link android.bluetooth.BluetoothGatt#close close()} +so the system can release resources appropriately:</p> + +<pre>public void close() { + if (mBluetoothGatt == null) { + return; + } + mBluetoothGatt.close(); + mBluetoothGatt = null; +}</pre> diff --git a/docs/html/guide/topics/connectivity/bluetooth.jd b/docs/html/guide/topics/connectivity/bluetooth.jd index 1c55d8b..b57f3e2 100644 --- a/docs/html/guide/topics/connectivity/bluetooth.jd +++ b/docs/html/guide/topics/connectivity/bluetooth.jd @@ -2,19 +2,13 @@ page.title=Bluetooth page.tags="wireless","bluetoothadapter","bluetoothdevice" @jd:body -<div id="qv-wrapper"> -<div id="qv"> +<div id="qv-wrapper"> +<div id="qv"> - <h2>Quickview</h2> - <ul> - <li>Android's bluetooth APIs allow your application to perform wireless data transactions with -other devices</li> - </ul> - - <h2>In this document</h2> + <h2>In this document</h2> <ol> - <li><a href="#TheBasics">The Basics</a></li> - <li><a href="#Permissions">Bluetooth Permissions</a></li> + <li><a href="#TheBasics">The Basics</a></li> + <li><a href="#Permissions">Bluetooth Permissions</a></li> <li><a href="#SettingUp">Setting Up Bluetooth</a></li> <li><a href="#FindingDevices">Finding Devices</a> <ol> @@ -70,6 +64,11 @@ following:</p> <li>Manage multiple connections</li> </ul> +<p>This document describes how to use <em>Classic Bluetooth</em>. Classic +Bluetooth is the right choice for more battery-intensive operations such as streaming +and communicating between Android devices. For Bluetooth devices with low power requirements, +Android 4.3 (API Level 18) introduces API support for Bluetooth Low Energy. To learn more, +see <a href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Low Energy</a>.</p> <h2 id="TheBasics">The Basics</h2> @@ -164,22 +163,18 @@ is, the internal service that runs a particular profile). </dd> <h2 id="Permissions">Bluetooth Permissions</h2> -<p>In order to use Bluetooth features in your application, you need to declare -at least one of two Bluetooth permissions: {@link -android.Manifest.permission#BLUETOOTH} and {@link -android.Manifest.permission#BLUETOOTH_ADMIN}.</p> - -<p>You must request the {@link android.Manifest.permission#BLUETOOTH} permission -in order to perform any Bluetooth communication, such as requesting a -connection, accepting a connection, and transferring data.</p> - -<p>You must request the {@link android.Manifest.permission#BLUETOOTH_ADMIN} -permission in order to initiate device discovery or manipulate Bluetooth -settings. Most applications need this permission solely for the +<p>In order to use Bluetooth features in your application, you must declare +the Bluetooth permission {@link android.Manifest.permission#BLUETOOTH}. +You need this permission to perform any Bluetooth communication, +such as requesting a connection, accepting a connection, and transferring data.</p> + +<p>If you want your app to initiate device discovery or manipulate Bluetooth +settings, you must also declare the {@link android.Manifest.permission#BLUETOOTH_ADMIN} +permission. Most applications need this permission solely for the ability to discover local Bluetooth devices. The other abilities granted by this permission should not be used, unless the application is a "power manager" that will modify Bluetooth settings upon user request. <strong>Note:</strong> If you -use {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission, then must +use {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission, then you must also have the {@link android.Manifest.permission#BLUETOOTH} permission.</p> <p>Declare the Bluetooth permission(s) in your application manifest file. For diff --git a/docs/html/guide/topics/graphics/hardware-accel.jd b/docs/html/guide/topics/graphics/hardware-accel.jd index 04fb564..8ba6676 100644 --- a/docs/html/guide/topics/graphics/hardware-accel.jd +++ b/docs/html/guide/topics/graphics/hardware-accel.jd @@ -47,35 +47,24 @@ parent.link=index.html </div> </div> - <p>Beginning in Android 3.0 (API level 11), the Android 2D rendering pipeline is designed to - better support hardware acceleration. Hardware acceleration carries out all drawing operations - that are performed on a {@link android.view.View}'s canvas using the GPU. Because of the - increased resources required to enable hardware acceleration, your app will consume more RAM.</p> - - <p>The easiest way to enable hardware acceleration is to turn it on - globally for your entire application. If your application uses only standard views and {@link - android.graphics.drawable.Drawable}s, turning it on globally should not cause any adverse - drawing effects. However, because hardware acceleration is not supported for all of the 2D drawing - operations, turning it on might affect some of your applications that use custom views or drawing - calls. Problems usually manifest themselves as invisible elements, exceptions, or wrongly - rendered pixels. To remedy this, Android gives you the option to enable or disable hardware - acceleration at the following levels:</p> - - <ul> - <li>Application</li> - - <li>Activity</li> - - <li>Window</li> - - <li>View</li> - </ul> - - <p>If your application performs custom drawing, test your application on actual hardware -devices with hardware acceleration turned on to find any problems. The <a -href="#drawing-support">Unsupported drawing operations</a> section describes known issues with -drawing operations that cannot be hardware accelerated and how to work around them.</p> - + <p>Beginning in Android 3.0 (API level 11), the Android 2D rendering pipeline supports hardware + acceleration, meaning that all drawing operations that are performed on a {@link + android.view.View}'s canvas use the GPU. Because of the increased resources required to enable + hardware acceleration, your app will consume more RAM.</p> + + <p>Hardware acceleration is enabled by default if your Target API level is >=14, but can also + be explicitly enabled. If your application uses only standard views and {@link + android.graphics.drawable.Drawable}s, turning it on globally should not cause any adverse drawing + effects. However, because hardware acceleration is not supported for all of the 2D drawing + operations, turning it on might affect some of your custom views or drawing calls. Problems + usually manifest themselves as invisible elements, exceptions, or wrongly rendered pixels. To + remedy this, Android gives you the option to enable or disable hardware acceleration at multiple + levels. See <a href="#controlling">Controlling Hardware Acceleration</a>.</p> + + <p>If your application performs custom drawing, test your application on actual hardware devices + with hardware acceleration turned on to find any problems. The <a + href="#drawing-support">Unsupported drawing operations</a> section describes known issues with + hardware acceleration and how to work around them.</p> <h2 id="controlling">Controlling Hardware Acceleration</h2> <p>You can control hardware acceleration at the following levels:</p> @@ -100,12 +89,12 @@ drawing operations that cannot be hardware accelerated and how to work around th </pre> <h4>Activity level</h4> - <p>If your application does not behave properly with hardware acceleration turned on globally, - you can control it for individual activities as well. To enable or disable hardware acceleration - at the activity level, you can use the <code>android:hardwareAccelerated</code> - attribute for the <a href="{@docRoot}guide/topics/manifest/activity-element.html"> - <code><activity></code></a> element. The following example enables hardware acceleration -for the entire application but disables it for one activity:</p> + <p>If your application does not behave properly with hardware acceleration turned on globally, you + can control it for individual activities as well. To enable or disable hardware acceleration at + the activity level, you can use the <code>android:hardwareAccelerated</code> attribute for + the <a href="{@docRoot}guide/topics/manifest/activity-element.html"> + <code><activity></code></a> element. The following example enables hardware acceleration for + the entire application but disables it for one activity:</p> <pre> <application android:hardwareAccelerated="true"> @@ -228,8 +217,7 @@ changed.</li> <p>With this model, you cannot rely on a view intersecting the dirty region to have its {@link android.view.View#draw draw()} method executed. To ensure that the Android system records a view’s display list, you must call {@link android.view.View#invalidate invalidate()}. Forgetting - to do so causes a view to look the same even after changing it, which is an easier bug to find if - it happens.</p> + to do so causes a view to look the same even after it has been changed.</p> <p>Using display lists also benefits animation performance because setting specific properties, such as alpha or rotation, does not require invalidating the targeted view (it is done @@ -270,119 +258,353 @@ changed.</li> android.graphics.Canvas} drawing operations as well as many less-used operations. All of the drawing operations that are used to render applications that ship with Android, default widgets and layouts, and common advanced visual effects such as reflections and tiled textures are - supported. The following list describes known operations that are <strong>not supported</strong> - with hardware acceleration:</p> - - <ul> - <li> - <strong>Canvas</strong> - - <ul> - <li>{@link android.graphics.Canvas#clipPath clipPath()}</li> - - <li>{@link android.graphics.Canvas#clipRegion clipRegion()}</li> - - <li>{@link android.graphics.Canvas#drawPicture drawPicture()}</li> - - <li>{@link android.graphics.Canvas#drawTextOnPath drawTextOnPath()}</li> - - <li>{@link android.graphics.Canvas#drawVertices drawVertices()}</li> - </ul> - </li> - - <li> - <strong>Paint</strong> - - <ul> - <li>{@link android.graphics.Paint#setLinearText setLinearText()}</li> - - <li>{@link android.graphics.Paint#setMaskFilter setMaskFilter()}</li> - - <li>{@link android.graphics.Paint#setRasterizer setRasterizer()}</li> - </ul> - </li> - - <li> - <strong>Xfermodes</strong> - - <ul> - <li>{@link android.graphics.AvoidXfermode AvoidXfermode}</li> - - <li>{@link android.graphics.PixelXorXfermode PixelXorXfermode}</li> - </ul> - </li> - </ul> - - <p>In addition, some operations behave differently with hardware acceleration enabled:</p> - - <ul> - <li> - <strong>Canvas</strong> - - <ul> - <li>{@link android.graphics.Canvas#clipRect clipRect()}: <code>XOR</code>, - <code>Difference</code> and <code>ReverseDifference</code> clip modes are ignored. 3D - transforms do not apply to the clip rectangle</li> - - <li>{@link android.graphics.Canvas#drawBitmapMesh drawBitmapMesh()}: colors array is - ignored</li> - </ul> - </li> - - <li> - <strong>Paint</strong> - - <ul> - <li>{@link android.graphics.Paint#setDither setDither()}: ignored</li> - - <li>{@link android.graphics.Paint#setFilterBitmap setFilterBitmap()}: filtering is always - on</li> - - <li>{@link android.graphics.Paint#setShadowLayer setShadowLayer()}: works with text - only</li> - </ul> - </li> - - <li> - <strong>PorterDuffXfermode</strong> - - <ul> - <li>{@link android.graphics.PorterDuff.Mode#DARKEN PorterDuff.Mode.DARKEN} will - be equivalent to {@link android.graphics.PorterDuff.Mode#SRC_OVER} when blending - against the framebuffer.</li> - - <li>{@link android.graphics.PorterDuff.Mode#LIGHTEN PorterDuff.Mode.LIGHTEN} will - be equivalent to {@link android.graphics.PorterDuff.Mode#SRC_OVER} when blending - against the framebuffer.</li> - - <li>{@link android.graphics.PorterDuff.Mode#OVERLAY PorterDuff.Mode.OVERLAY} will - be equivalent to {@link android.graphics.PorterDuff.Mode#SRC_OVER} when blending - against the framebuffer.</li> - </ul> - </li> - - <li> - <strong>ComposeShader</strong> - - <ul> - <li>{@link android.graphics.ComposeShader} can only contain shaders of different types (a - {@link android.graphics.BitmapShader} and a {@link android.graphics.LinearGradient} for - instance, but not two instances of {@link android.graphics.BitmapShader} )</li> - - <li>{@link android.graphics.ComposeShader} cannot contain a {@link - android.graphics.ComposeShader}</li> - </ul> - </li> - </ul> + supported.</p> + + <p>The following table describes the support level of various operations across API levels:</p> + + <style type="text/css"> + .tblGenFixed, .tblGeneric{font-size:15px}.tblGenFixed td {padding:0 3px;letter-spacing:0;word-spacing:0;background-color:#fff;z-index:1;border-top:0px none;border-left:0px none;border-bottom:1px solid #CCC;border-right:1px solid #CCC;} .dn {display:none} .tblGenFixed td.s0 {background-color:white;border-top:1px solid #CCC;border-left:1px solid #CCC;} .tblGenFixed td.s1 {background-color:#434343;color:#ffffff;text-align:center;border-top:1px solid #CCC;} .tblGenFixed td.s2 {background-color:#d9d9d9;color:#000000;text-align:center;} .tblGenFixed td.s3 {background-color:white;color:#000000;text-align:center;} .tblGenFixed td.s5 {background-color:#434343;color:#ffffff;text-align:left;border-left:1px solid #CCC;} .tblGenFixed td.s10 {background-color:white;font-family:courier new,monospace;color:#000000;text-align:right;border-left:1px solid #CCC;} .tblGenFixed td.g_pos {background-color:#d9d9d9;color:#6aa84f;text-align:center;} .tblGenFixed td.g_neg {background-color:#d9d9d9;color:#980000;text-align:center;} .tblGenFixed td.w_pos {background-color:white;color:#6aa84f;text-align:center;} .tblGenFixed td.w_neg {background-color:white;color:#980000;text-align:center;} + </style> + <table border="0" cellpadding="0" cellspacing="0" class="tblGenFixed" id="tblMain"> + <tbody> + <tr class="rShim"> + <td class="rShim" style="width:380px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + </tr> + <tr> + <td rowspan="2" class="s0"></td> + <td colspan="4" class="s1">API level</td> + </tr> + <tr> + <td style="display:none;"></td> + <td class="s2">< 16</td> + <td class="s3">16</td> + <td class="s2">17</td> + <td class="s3">18</td> + </tr> + <tr> + <td colspan="5" class="s5">Canvas</td> + </tr> + <tr> + <td class="s10">drawBitmapMesh() (colors array)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">drawPicture()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">drawPosText()</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">drawTextOnPath()</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">drawVertices()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setDrawFilter()</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipPath()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRegion()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect(Region.Op.XOR)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect(Region.Op.Difference)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect(Region.Op.ReverseDifference)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect() with rotation/perspective</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td colspan="5" class="s5">Paint</td> + </tr> + <tr> + <td class="s10">setAntiAlias() (for text)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setAntiAlias() (for lines)</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setFilterBitmap()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setLinearText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setMaskFilter()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setPathEffect() (for lines)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setRasterizer()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setShadowLayer() (other than text)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setStrokeCap() (for lines)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setStrokeCap() (for points)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setSubpixelText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td colspan="5" class="s5">Xfermode</td> + </tr> + <tr> + <td class="s10">AvoidXfermode</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PixelXorXfermode</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PorterDuff.Mode.DARKEN (framebuffer)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PorterDuff.Mode.LIGHTEN (framebuffer)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PorterDuff.Mode.OVERLAY (framebuffer)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td colspan="5" class="s5">Shader</td> + </tr> + <tr> + <td class="s10">ComposeShader inside ComposeShader</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">Same type shaders inside ComposeShader</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">Local matrix on ComposeShader</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + </tbody> + </table> + + <h3 id="scaling">Canvas Scaling</h3> + + <p>The hardware accelerated 2D rendering pipeline was built first to support unscaled drawing, + with some drawing operations degrading quality significantly at higher scale values. These + operations are implemented as textures drawn at scale 1.0, transformed by the GPU. In API level + <17, using these operations will result in scaling artifacts increasing with scale.</p> + + The following table shows when implementation was changed to correctly handle large scales: + + <table border="0" cellpadding="0" cellspacing="0" class="tblGenFixed" id="tblMain"> + <tbody> + <tr class="rShim"> + <td class="rShim" style="width:380px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + </tr> + <tr> + <td rowspan="2" class="s0"></td> + <td colspan="4" class="s1">API level</td> + </tr> + <tr> + <td style="display:none;"></td> + <td class="s2">< 17</td> + <td class="s3">17</td> + <td class="s2">18</td> + </tr> + <tr> + <td colspan="5" class="s5">Support for large scale factors</td> + </tr> + <tr> + <td class="s10">drawText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_pos">✓</td> + </tr> + <tr> + <td class="s10">drawPosText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">drawTextOnPath()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">Simple Shapes*</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + </tr> + <tr> + <td class="s10">Complex Shapes*</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">drawPath()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">Shadow layer</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + </tbody> + </table> + + <p class="note"><strong>Note</strong>: 'Simple' shapes are <code>drawRect()</code>, + <code>drawCircle()</code>, <code>drawOval()</code>, <code>drawRoundRect()</code>, and + <code>drawArc()</code> (with useCenter=false) commands issued with a Paint that doesn't have a + PathEffect, and doesn't contain non-default joins (via <code>setStrokeJoin()</code> / + <code>setStrokeMiter()</code>). Other instances of those draw commands fall under 'Complex,' in + the above chart.</p> <p>If your application is affected by any of these missing features or limitations, you can turn - off hardware acceleration for just the affected portion of your application by calling - {@link android.view.View#setLayerType setLayerType(View.LAYER_TYPE_SOFTWARE, null)}. This way, -you can still take advantage of hardware acceleratin everywhere else. See <a -href="#controlling">Controlling Hardware Acceleration</a> for more information on how to enable and -disable hardware acceleration at different levels in your application. - - + off hardware acceleration for just the affected portion of your application by calling {@link + android.view.View#setLayerType setLayerType(View.LAYER_TYPE_SOFTWARE, null)}. This way, you can + still take advantage of hardware acceleration everywhere else. See <a + href="#controlling">Controlling Hardware Acceleration</a> for more information on how to enable + and disable hardware acceleration at different levels in your application. <h2 id="layers">View Layers</h2> diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd index 469eae2..f46113d 100644 --- a/docs/html/guide/topics/graphics/opengl.jd +++ b/docs/html/guide/topics/graphics/opengl.jd @@ -1,4 +1,4 @@ -page.title=OpenGL +page.title=OpenGL ES page.tags="games" @jd:body @@ -9,21 +9,21 @@ page.tags="games" <ol> <li><a href="#basics">The Basics</a> <ol> - <li><a href="#packages">OpenGL packages</a></li> + <li><a href="#packages">OpenGL ES packages</a></li> </ol> <li><a href="#manifest">Declaring OpenGL Requirements</a></li> - </li> <li><a href="#coordinate-mapping">Mapping Coordinates for Drawn Objects</a> <ol> <li><a href="#proj-es1">Projection and camera in ES 1.0</a></li> - <li><a href="#proj-es1">Projection and camera in ES 2.0</a></li> + <li><a href="#proj-es2">Projection and camera in ES 2.0 and higher</a></li> </ol> </li> - <li><a href="#faces-winding">Shape Faces and Winding</li> + <li><a href="#faces-winding">Shape Faces and Winding</a></li> <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a> <ol> <li><a href="#textures">Texture compression support</a></li> - <li><a href="#gl-extension-query">Determining OpenGL Extensions</a></li> + <li><a href="#gl-extension-query">Determining OpenGL extensions</a></li> + <li><a href="#version-check">Checking OpenGL ES Version</a></li> </ol> </li> <li><a href="#choosing-version">Choosing an OpenGL API Version</a></li> @@ -48,20 +48,37 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li> <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li> <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li> + <li><a href="http://www.khronos.org/opengles/3_X/">OpenGL ES 3.x specification</a></li> </ol> </div> </div> <p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library -(OpenGL), specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that specifies a +(OpenGL®), specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that specifies a standard software interface for 3D graphics processing hardware. OpenGL ES is a flavor of the OpenGL -specification intended for embedded devices. The OpenGL ES 1.0 and 1.1 API specifications have been -supported since Android 1.0. Beginning with Android 2.2 (API Level 8), the framework supports the -OpenGL ES 2.0 API specification.</p> +specification intended for embedded devices. Android supports several versions of the OpenGL ES +API:</p> + +<ul> + <li>OpenGL ES 1.0 and 1.1 - This API specification is supported by Android 1.0 and higher.</li> + <li>OpenGL ES 2.0 - This API specification is supported by Android 2.2 (API level 8) and higher. + </li> + <li>OpenGL ES 3.0 - This API specification is supported by Android 4.3 (API level 18) and higher. + </li> +</ul> + +<p class="caution"><strong>Caution:</strong> + Support of the OpenGL ES 3.0 API on a device requires an implementation of this graphics + pipeline provided by the device manufacturer. A device running Android 4.3 or higher <em>may + not support</em> the OpenGL ES 3.0 API. For information on checking what version of OpenGL ES + is supported at run time, see <a href="#version-check">Checking OpenGL ES Version</a>. +</p> + +<p class="note"><strong>Note:</strong> + The specific API provided by the Android framework is similar to the J2ME JSR239 OpenGL ES API, + but is not identical. If you are familiar with J2ME JSR239 specification, be alert for + variations.</p> -<p class="note"><b>Note:</b> The specific API provided by the Android framework is similar to the - J2ME JSR239 OpenGL ES API, but is not identical. If you are familiar with J2ME JSR239 - specification, be alert for variations.</p> <h2 id="basics">The Basics</h2> @@ -87,7 +104,7 @@ understanding how to implement these classes in an activity should be your first <a href="{@docRoot}training/graphics/opengl/touch.html">Responding to Touch Events</a>.</dd> <dt><strong>{@link android.opengl.GLSurfaceView.Renderer}</strong></dt> - <dd>This interface defines the methods required for drawing graphics in an OpenGL {@link + <dd>This interface defines the methods required for drawing graphics in a {@link android.opengl.GLSurfaceView}. You must provide an implementation of this interface as a separate class and attach it to your {@link android.opengl.GLSurfaceView} instance using {@link android.opengl.GLSurfaceView#setRenderer(android.opengl.GLSurfaceView.Renderer) @@ -123,51 +140,59 @@ understanding how to implement these classes in an activity should be your first </dd> </dl> -<h3 id="packages">OpenGL packages</h3> -<p>Once you have established a container view for OpenGL using {@link +<h3 id="packages">OpenGL ES packages</h3> +<p>Once you have established a container view for OpenGL ES using {@link android.opengl.GLSurfaceView} and {@link android.opengl.GLSurfaceView.Renderer}, you can begin calling OpenGL APIs using the following classes:</p> <ul> <li>OpenGL ES 1.0/1.1 API Packages <ul> - <li>{@link android.opengl} - This package provides a static interface to the OpenGL ES -1.0/1.1 classes and better performance than the javax.microedition.khronos package interfaces. - <ul> - <li>{@link android.opengl.GLES10}</li> - <li>{@link android.opengl.GLES10Ext}</li> - <li>{@link android.opengl.GLES11}</li> - <li>{@link android.opengl.GLES11Ext}</li> - </ul> - </li> + <li>{@link android.opengl} - This package provides a static interface to the OpenGL ES + 1.0/1.1 classes and better performance than the {@code javax.microedition.khronos} package + interfaces. + <ul> + <li>{@link android.opengl.GLES10}</li> + <li>{@link android.opengl.GLES10Ext}</li> + <li>{@link android.opengl.GLES11}</li> + <li>{@link android.opengl.GLES11Ext}</li> + </ul> + </li> <li>{@link javax.microedition.khronos.opengles} - This package provides the standard -implementation of OpenGL ES 1.0/1.1. - <ul> - <li>{@link javax.microedition.khronos.opengles.GL10}</li> - <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li> - <li>{@link javax.microedition.khronos.opengles.GL11}</li> - <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li> - <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li> - </ul> + implementation of OpenGL ES 1.0/1.1. + <ul> + <li>{@link javax.microedition.khronos.opengles.GL10}</li> + <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li> + <li>{@link javax.microedition.khronos.opengles.GL11}</li> + <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li> + <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li> + </ul> </li> </ul> </li> <li>OpenGL ES 2.0 API Class <ul> <li>{@link android.opengl.GLES20 android.opengl.GLES20} - This package provides the -interface to OpenGL ES 2.0 and is available starting with Android 2.2 (API Level 8).</li> + interface to OpenGL ES 2.0 and is available starting with Android 2.2 (API level 8).</li> + </ul> + </li> + <li>OpenGL ES 3.0 API Class + <ul> + <li>{@link android.opengl.GLES30 android.opengl.GLES30} - This package provides the + interface to OpenGL ES 3.0 and is available starting with Android 4.3 (API level 18).</li> </ul> </li> </ul> -<p>If you'd like to start building an app with OpenGL right away, follow the -<a href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> class. +<p>If you want to start building an app with OpenGL ES right away, follow the +<a href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> +class. </p> <h2 id="manifest">Declaring OpenGL Requirements</h2> <p>If your application uses OpenGL features that are not available on all devices, you must include these requirements in your <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a></code> file. +href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file. Here are the most common OpenGL manifest declarations:</p> <ul> @@ -176,12 +201,28 @@ Here are the most common OpenGL manifest declarations:</p> shown below. <pre> - <!-- Tell the system this app requires OpenGL ES 2.0. --> - <uses-feature android:glEsVersion="0x00020000" android:required="true" /> +<!-- Tell the system this app requires OpenGL ES 2.0. --> +<uses-feature android:glEsVersion="0x00020000" android:required="true" /> +</pre> + + <p>Adding this declaration causes Google Play to restrict your application from being + installed on devices that do not support OpenGL ES 2.0. If your application is exclusively for + devices that support OpenGL ES 3.0, you can also specify this in your manifest:</p> + +<pre> +<!-- Tell the system this app requires OpenGL ES 3.0. --> +<uses-feature android:glEsVersion="0x00030000" android:required="true" /> </pre> - <p>Adding this declaration causes Google Play to restrict your application from being - installed on devices that do not support OpenGL ES 2.0.</p> + <p class="note"><strong>Note:</strong> + The OpenGL ES 3.0 API is backwards-compatible with the 2.0 API, which means you can be more + flexible with your implementation of OpenGL ES in your application. By declaring the OpenGL + ES 2.0 API as a requirement in your manifest, you can use that API version as a default, check + for the availability of the 3.0 API at run time and then use OpenGL ES 3.0 features if the + device supports it. For more information about checking the OpenGL ES version supported by a + device, see <a href="#version-check">Checking OpenGL ES Version</a>. + </p> + </li> <li><strong>Texture compression requirements</strong> - If your application uses texture compression formats, you must declare the formats your application supports in your manifest file @@ -221,6 +262,7 @@ matrix and apply them to the OpenGL rendering pipeline. The projection matrix re coordinates of your graphics so that they map correctly to Android device screens. The camera view matrix creates a transformation that renders objects from a specific eye position.</p> + <h3 id="proj-es1">Projection and camera view in OpenGL ES 1.0</h3> <p>In the ES 1.0 API, you apply projection and camera view by creating each matrix and then adding them to the OpenGL environment.</p> @@ -235,15 +277,15 @@ implementation to create a projection matrix based on the screen's aspect ratio OpenGL rendering environment. <pre> - public void onSurfaceChanged(GL10 gl, int width, int height) { - gl.glViewport(0, 0, width, height); - - // make adjustments for screen ratio - float ratio = (float) width / height; - gl.glMatrixMode(GL10.GL_PROJECTION); // set matrix to projection mode - gl.glLoadIdentity(); // reset the matrix to its default state - gl.glFrustumf(-ratio, ratio, -1, 1, 3, 7); // apply the projection matrix - } +public void onSurfaceChanged(GL10 gl, int width, int height) { + gl.glViewport(0, 0, width, height); + + // make adjustments for screen ratio + float ratio = (float) width / height; + gl.glMatrixMode(GL10.GL_PROJECTION); // set matrix to projection mode + gl.glLoadIdentity(); // reset the matrix to its default state + gl.glFrustumf(-ratio, ratio, -1, 1, 3, 7); // apply the projection matrix +} </pre> </li> @@ -258,24 +300,25 @@ float, float, float, float, float, float) GLU.gluLookAt()} utility to create a v which simulates a camera position. <pre> - public void onDrawFrame(GL10 gl) { - ... - // Set GL_MODELVIEW transformation mode - gl.glMatrixMode(GL10.GL_MODELVIEW); - gl.glLoadIdentity(); // reset the matrix to its default state - - // When using GL_MODELVIEW, you must set the camera view - GLU.gluLookAt(gl, 0, 0, -5, 0f, 0f, 0f, 0f, 1.0f, 0.0f); - ... - } +public void onDrawFrame(GL10 gl) { + ... + // Set GL_MODELVIEW transformation mode + gl.glMatrixMode(GL10.GL_MODELVIEW); + gl.glLoadIdentity(); // reset the matrix to its default state + + // When using GL_MODELVIEW, you must set the camera view + GLU.gluLookAt(gl, 0, 0, -5, 0f, 0f, 0f, 0f, 1.0f, 0.0f); + ... +} </pre> </li> </ol> -<h3 id="proj-es2">Projection and camera view in OpenGL ES 2.0</h3> -<p>In the ES 2.0 API, you apply projection and camera view by first adding a matrix member to -the vertex shaders of your graphics objects. With this matrix member added, you can then +<h3 id="proj-es2">Projection and camera view in OpenGL ES 2.0 and higher</h3> + +<p>In the ES 2.0 and 3.0 APIs, you apply projection and camera view by first adding a matrix member +to the vertex shaders of your graphics objects. With this matrix member added, you can then generate and apply projection and camera viewing matrices to your objects.</p> <ol> @@ -285,20 +328,20 @@ code, the included {@code uMVPMatrix} member allows you to apply projection and matrices to the coordinates of objects that use this shader. <pre> - private final String vertexShaderCode = +private final String vertexShaderCode = - // This matrix member variable provides a hook to manipulate - // the coordinates of objects that use this vertex shader. - "uniform mat4 uMVPMatrix; \n" + + // This matrix member variable provides a hook to manipulate + // the coordinates of objects that use this vertex shader. + "uniform mat4 uMVPMatrix; \n" + - "attribute vec4 vPosition; \n" + - "void main(){ \n" + - // The matrix must be included as part of gl_Position - // Note that the uMVPMatrix factor *must be first* in order - // for the matrix multiplication product to be correct. - " gl_Position = uMVPMatrix * vPosition; \n" + + "attribute vec4 vPosition; \n" + + "void main(){ \n" + + // The matrix must be included as part of gl_Position + // Note that the uMVPMatrix factor *must be first* in order + // for the matrix multiplication product to be correct. + " gl_Position = uMVPMatrix * vPosition; \n" + - "} \n"; + "} \n"; </pre> <p class="note"><strong>Note:</strong> The example above defines a single transformation matrix member in the vertex shader into which you apply a combined projection matrix and camera view @@ -315,38 +358,35 @@ android.opengl.GLSurfaceView.Renderer} implementation to access the matrix variable defined in the vertex shader above. <pre> - public void onSurfaceCreated(GL10 unused, EGLConfig config) { - ... - muMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix"); - ... - } +public void onSurfaceCreated(GL10 unused, EGLConfig config) { + ... + muMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix"); + ... +} </pre> </li> <li><strong>Create projection and camera viewing matrices</strong> - Generate the projection and viewing matrices to be applied the graphic objects. The following example code shows how to modify -the {@link -android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10, -javax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()} and {@link -android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10, -int, int) onSurfaceChanged()} methods of a {@link android.opengl.GLSurfaceView.Renderer} -implementation to create camera view matrix and a projection matrix based on the screen aspect ratio -of the device. +the {@link android.opengl.GLSurfaceView.Renderer#onSurfaceCreated onSurfaceCreated()} and +{@link android.opengl.GLSurfaceView.Renderer#onSurfaceChanged onSurfaceChanged()} methods of a +{@link android.opengl.GLSurfaceView.Renderer} implementation to create camera view matrix and a +projection matrix based on the screen aspect ratio of the device. <pre> - public void onSurfaceCreated(GL10 unused, EGLConfig config) { - ... - // Create a camera view matrix - Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f); - } +public void onSurfaceCreated(GL10 unused, EGLConfig config) { + ... + // Create a camera view matrix + Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f); +} - public void onSurfaceChanged(GL10 unused, int width, int height) { - GLES20.glViewport(0, 0, width, height); +public void onSurfaceChanged(GL10 unused, int width, int height) { + GLES20.glViewport(0, 0, width, height); - float ratio = (float) width / height; + float ratio = (float) width / height; - // create a projection matrix from device screen geometry - Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7); - } + // create a projection matrix from device screen geometry + Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7); +} </pre> </li> @@ -359,23 +399,24 @@ the projection matrix and camera view created in the code above and then apply i objects to be rendered by OpenGL. <pre> - public void onDrawFrame(GL10 unused) { - ... - // Combine the projection and camera view matrices - Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0); +public void onDrawFrame(GL10 unused) { + ... + // Combine the projection and camera view matrices + Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0); - // Apply the combined projection and camera view transformations - GLES20.glUniformMatrix4fv(muMVPMatrixHandle, 1, false, mMVPMatrix, 0); + // Apply the combined projection and camera view transformations + GLES20.glUniformMatrix4fv(muMVPMatrixHandle, 1, false, mMVPMatrix, 0); - // Draw objects - ... - } + // Draw objects + ... +} </pre> </li> </ol> <p>For a complete example of how to apply projection and camera view with OpenGL ES 2.0, see the <a href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> class.</p> + <h2 id="faces-winding">Shape Faces and Winding</h2> <p>In OpenGL, the face of a shape is a surface defined by three or more points in three-dimensional @@ -414,35 +455,55 @@ So, always define the coordinates of your OpenGL shapes in a counterclockwise dr clockwise face as the front face, but doing so requires more code and is likely to confuse experienced OpenGL developers when you ask them for help. So don’t do that.</p> + <h2 id="compatibility">OpenGL Versions and Device Compatibility</h2> <p>The OpenGL ES 1.0 and 1.1 API specifications have been supported since Android 1.0. -Beginning with Android 2.2 (API Level 8), the framework supports the OpenGL ES 2.0 API +Beginning with Android 2.2 (API level 8), the framework supports the OpenGL ES 2.0 API specification. OpenGL ES 2.0 is supported by most Android devices and is recommended for new -applications being developed with OpenGL. For information about the relative number of -Android-powered devices that support a given version of OpenGL ES, see the <a -href="{@docRoot}resources/dashboard/opengl.html">OpenGL ES Versions Dashboard</a>.</p> +applications being developed with OpenGL. OpenGL ES 3.0 is supported with Android 4.3 +(API level 18) and higher, on devices that provide an implementation of the OpenGL ES 3.0 API. +For information about the relative number of Android-powered devices +that support a given version of OpenGL ES, see the +<a href="{@docRoot}about/dashboards/index.html#OpenGL">OpenGL ES Version Dashboard</a>.</p> + +<p>Graphics programming with OpenGL ES 1.0/1.1 API is significantly different than using the 2.0 +and higher versions. The 1.x version of the API has more convenience methods and a fixed graphics +pipeline, while the OpenGL ES 2.0 and 3.0 APIs provide more direct control of the pipeline through +use of OpenGL shaders. You should carefully consider the graphics requirements and choose the API +version that works best for your application. For more information, see +<a href="#choosing-version">Choosing an OpenGL API Version</a>.</p> + +<p>The OpenGL ES 3.0 API provides additional features and better performance than the 2.0 API and is +also backward compatible. This means that you can potentially write your application targeting +OpenGL ES 2.0 and conditionally include OpenGL ES 3.0 graphics features if they are available. For +more information on checking for availability of the 3.0 API, see +<a href="#version-check">Checking OpenGL ES Version</a></p> <h3 id="textures">Texture compression support</h3> + <p>Texture compression can significantly increase the performance of your OpenGL application by reducing memory requirements and making more efficient use of memory bandwidth. The Android framework provides support for the ETC1 compression format as a standard feature, including a {@link android.opengl.ETC1Util} utility class and the {@code etc1tool} compression tool (located in the Android SDK at {@code <sdk>/tools/}). For an example of an Android application that uses -texture compression, see the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/CompressedTextureActivity.html" ->CompressedTextureActivity</a> code sample.</p> +texture compression, see the {@code CompressedTextureActivity} code sample in Android SDK +({@code <sdk>/samples/<version>/ApiDemos/src/com/example/android/apis/graphics/}).</p> -<p>The ETC format is supported by most Android devices, but it not guarranteed to be available. To -check if the ETC1 format is supported on a device, call the {@link -android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p> +<p class="caution"><strong>Caution:</strong> The ETC1 format is supported by most Android devices, +but it not guaranteed to be available. To check if the ETC1 format is supported on a device, call +the {@link android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p> <p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an -alpha channel. If your application requires textures with an alpha channel, you should +transparency (alpha channel). If your application requires textures with transparency, you should investigate other texture compression formats available on your target devices.</p> -<p>Beyond the ETC1 format, Android devices have varied support for texture compression based on +<p>The ETC2/EAC texture compression formats are guaranteed to be available when using the OpenGL ES +3.0 API. This texture format offers excellent compression ratios with high visual quality and the +format also supports transparency (alpha channel).</p> + +<p>Beyond the ETC formats, Android devices have varied support for texture compression based on their GPU chipsets and OpenGL implementations. You should investigate texture compression support on the devices you are are targeting to determine what compression types your application should support. In order to determine what texture formats are supported on a given device, you must <a @@ -479,11 +540,12 @@ names, for example: </ul> </li> <li><strong>3DC</strong> - 3DC texture compression (3DC) is a less widely available format that -supports RGB textures with an an alpha channel. This format is represented by the following OpenGL -extension name:</li> +supports RGB textures with an alpha channel. This format is represented by the following OpenGL +extension name: <ul> <li>{@code GL_AMD_compressed_3DC_texture}</li> </ul> + </li> </ul> <p class="warning"><strong>Warning:</strong> These texture compression formats are <em>not @@ -500,6 +562,7 @@ your app is installed only on devices that support the formats your app requires <a href="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p> + <h3 id="gl-extension-query">Determining OpenGL extensions</h3> <p>Implementations of OpenGL vary by Android device in terms of the extensions to the OpenGL ES API that are supported. These extensions include texture compressions, but typically also include other @@ -511,9 +574,10 @@ particular device:</p> <li>Run the following code on your target devices to determine what texture compression formats are supported: <pre> - String extensions = javax.microedition.khronos.opengles.GL10.glGetString(GL10.GL_EXTENSIONS); +String extensions = javax.microedition.khronos.opengles.GL10.glGetString( + GL10.GL_EXTENSIONS); </pre> - <p class="warning"><b>Warning:</b> The results of this call <em>vary by device!</em> You + <p class="warning"><b>Warning:</b> The results of this call <em>vary by device model!</em> You must run this call on several target devices to determine what compression types are commonly supported.</p> </li> @@ -522,31 +586,105 @@ device.</li> </ol> +<h3 id="version-check">Checking OpenGL ES Version</h3> + +<p>There are several versions of the OpenGL ES available on Android devices. You can specify the +minimum version of the API your application requires in your <a href="#manifest">manifest</a>, but +you may also want to take advantage of features in a newer API at the same time. For example, +the OpenGL ES 3.0 API is backward-compatible with the 2.0 version of the API, so you may want to +write your application so that it uses OpenGL ES 3.0 features, but falls back to the 2.0 API if the +3.0 API is not available.</p> + +<p>Before using OpenGL ES features from a version higher than the minimum required in your +application manifest, your application should check the version of the API available on the device. +You can do this in one of two ways:</p> + +<ol> + <li>Attempt create the higher-level OpenGL ES context ({@link android.opengl.EGLContext}) and + check the result.</li> + <li>Create a minimum-supported OpenGL ES context and check the version value.</li> +</ol> + +<p>The following example code demonstrates how to check the available OpenGL ES version by creating +an {@link android.opengl.EGLContext} and checking the result. This example shows how to check for +OpenGL ES 3.0 version:</p> + +<pre> +private static double glVersion = 3.0; + +private static class ContextFactory implements GLSurfaceView.EGLContextFactory { + + private static int EGL_CONTEXT_CLIENT_VERSION = 0x3098; + + public EGLContext createContext( + EGL10 egl, EGLDisplay display, EGLConfig eglConfig) { + + Log.w(TAG, "creating OpenGL ES " + glVersion + " context"); + int[] attrib_list = {EGL_CONTEXT_CLIENT_VERSION, (int) glVersion, + EGL10.EGL_NONE }; + // attempt to create a OpenGL ES 3.0 context + EGLContext context = egl.eglCreateContext( + display, eglConfig, EGL10.EGL_NO_CONTEXT, attrib_list); + return context; // returns null if 3.0 is not supported; + } +} +</pre> + +<p>If the {@code createContext()} method show above returns null, your code should create a OpenGL +ES 2.0 context instead and fall back to using only that API.</p> + +<p>The following code example demonstrates how to check the OpenGL ES version by creating a minimum +supported context first, and then checking the version string:</p> + +<pre> +// Create a minimum supported OpenGL ES context, then check: +String version = javax.microedition.khronos.opengles.GL10.glGetString( + GL10.GL_VERSION); +Log.w(TAG, "Version: " + version ); +// The version format is displayed as: "OpenGL ES <major>.<minor>" +// followed by optional content provided by the implementation. +</pre> + +<p>With this approach, if you discover that the device supports a higher-level API version, you +must destroy the minimum OpenGL ES context and create a new context with the higher +available API version.</p> + + <h2 id="choosing-version">Choosing an OpenGL API Version</h2> -<p>OpenGL ES API version 1.0 (and the 1.1 extensions) and version 2.0 both provide high +<p>OpenGL ES 1.0 API version (and the 1.1 extensions), version 2.0, and version 3.0 all provide high performance graphics interfaces for creating 3D games, visualizations and user interfaces. Graphics -programming for the OpenGL ES 1.0/1.1 API versus ES 2.0 differs significantly, and so developers -should carefully consider the following factors before starting development with either API:</p> +progamming for OpenGL ES 2.0 and 3.0 is largely similar, with version 3.0 representing a superset +of the 2.0 API with additional features. Programming for the OpenGL ES 1.0/1.1 API versus OpenGL ES +2.0 and 3.0 differs significantly, and so developers should carefully consider the following +factors before starting development with these APIs:</p> <ul> - <li><strong>Performance</strong> - In general, OpenGL ES 2.0 provides faster graphics performance -than the ES 1.0/1.1 APIs. However, the performance difference can vary depending on the Android -device your OpenGL application is running on, due to differences in the implementation of the OpenGL -graphics pipeline.</li> + <li><strong>Performance</strong> - In general, OpenGL ES 2.0 and 3.0 provide faster graphics + performance than the ES 1.0/1.1 APIs. However, the performance difference can vary depending on + the Android device your OpenGL application is running on, due to differences in hardware + manufacturer's implementation of the OpenGL ES graphics pipeline.</li> <li><strong>Device Compatibility</strong> - Developers should consider the types of devices, -Android versions and the OpenGL ES versions available to their customers. For more information -on OpenGL compatibility across devices, see the <a href="#compatibility">OpenGL Versions and Device -Compatibility</a> section.</li> + Android versions and the OpenGL ES versions available to their customers. For more information + on OpenGL compatibility across devices, see the <a href="#compatibility">OpenGL Versions and + Device Compatibility</a> section.</li> <li><strong>Coding Convenience</strong> - The OpenGL ES 1.0/1.1 API provides a fixed function -pipeline and convenience functions which are not available in the ES 2.0 API. Developers who are new -to OpenGL may find coding for OpenGL ES 1.0/1.1 faster and more convenient.</li> - <li><strong>Graphics Control</strong> - The OpenGL ES 2.0 API provides a higher degree -of control by providing a fully programmable pipeline through the use of shaders. With more -direct control of the graphics processing pipeline, developers can create effects that would be -very difficult to generate using the 1.0/1.1 API.</li> + pipeline and convenience functions which are not available in the OpenGL ES 2.0 or 3.0 APIs. + Developers who are new to OpenGL ES may find coding for version 1.0/1.1 faster and more + convenient.</li> + <li><strong>Graphics Control</strong> - The OpenGL ES 2.0 and 3.0 APIs provide a higher degree + of control by providing a fully programmable pipeline through the use of shaders. With more + direct control of the graphics processing pipeline, developers can create effects that would be + very difficult to generate using the 1.0/1.1 API.</li> + <li><strong>Texture Support</strong> - The OpenGL ES 3.0 API has the best support for texture + compression because it guarantees availability of the ETC2 compression format, which supports + transparency. The 1.x and 2.0 API implementations usually include support for ETC1, however + this texture format does not support transparency and so you must typically provide resources + in other compression formats supported by the devices you are targeting. For more information, + see <a href="#textures">Texture compression support</a>.</li> </ul> <p>While performance, compatibility, convenience, control and other factors may influence your decision, you should pick an OpenGL API version based on what you think provides the best experience for your users.</p> + diff --git a/docs/html/guide/topics/graphics/renderscript/graphics.jd b/docs/html/guide/topics/graphics/renderscript/graphics.jd deleted file mode 100644 index 58676ea..0000000 --- a/docs/html/guide/topics/graphics/renderscript/graphics.jd +++ /dev/null @@ -1,994 +0,0 @@ -page.title=Graphics -parent.title=Renderscript -parent.link=index.html - -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li> - <a href="#creating-graphics-rs">Creating a Graphics Renderscript</a> - <ol> - <li><a href="#creating-native">Creating the Renderscript file</a></li> - <li><a href="#creating-entry">Creating the Renderscript entry point class</a></li> - <li><a href="#creating-view">Creating the view class</a></li> - <li><a href="#creating-activity">Creating the activity class</a></li> - </ol> - </li> - <li> - <a href="#drawing">Drawing</a> - <ol> - <li><a href="#drawing-rsg">Simple drawing</a></li> - <li><a href="#drawing-mesh">Drawing with a mesh</a></li> - </ol> - </li> - <li> - <a href="#shaders">Shaders</a> - <ol> - <li><a href="#shader-bindings">Shader bindings</a></li> - <li><a href="#shader-sampler">Defining a sampler</a></li> - </ol> - </li> - <li> - <a href="#fbo">Rendering to a Framebuffer Object</a> - </li> - </ol> - - <h2>Related Samples</h2> - - <ol> - <li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/FountainFbo/index.html">FountainFbo</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello -World</a></li> - - <li><a -href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samples</a></li> - </ol> - </div> - </div> - - <p>Renderscript provides a number of graphics APIs for rendering, both at the Android - framework level as well as at the Renderscript runtime level. For instance, the Android framework APIs let you - create meshes and define shaders to customize the graphical rendering pipeline. The native - Renderscript graphics APIs let you draw the actual meshes to render your scene. You need to - be familiar with both APIs to appropriately render graphics on an Android-powered device.</p> - - <h2 id="creating-graphics-rs">Creating a Graphics Renderscript</h2> - - <p>Renderscript applications require various layers of code, so it is useful to create the following - files to help keep your application organized:</p> - - <dl> - <dt>The Renderscript <code>.rs</code> file</dt> - - <dd>This file contains the logic to do the graphics rendering.</dd> - - <dt>The Renderscript entry point <code>.java</code> class</dt> - - <dd>This class allows the view class to interact with the code defined in the <code>.rs</code> - file. This class contains a Renderscript object (instance of - <code>ScriptC_<em>renderscript_file</em></code>), which allows your Android framework code to - call the Renderscript code. In general, this class does much of the setup for Renderscript - such as shader and mesh building and memory allocation and binding. The SDK samples follow the - convention of naming this file ActivityRS.java, - where Activity is the name of your main activity class.</dd> - - <dt>The view <code>.java</code> class</dt> - - <dd>This class extends {@link android.renderscript.RSSurfaceView} or {@link - android.renderscript.RSTextureView} to provide a surface to render on. A {@link - android.renderscript.RSSurfaceView} consumes a whole window, but a {@link - android.renderscript.RSTextureView} allows you to draw Renderscript graphics inside of a - view and add it to a {@link android.view.ViewGroup} alongside - other views. In this class, you create a {@link android.renderscript.RenderScriptGL} context object - with a call to {@link android.renderscript.RSSurfaceView#createRenderScriptGL - RSSurfaceView.createRenderscriptGL()} or {@link android.renderscript.RSTextureView#createRenderScriptGL - RSTextureView.createRenderscriptGL()}. The {@link android.renderscript.RenderScriptGL} context object - contains information about the current rendering state of Renderscript such as the vertex and - fragment shaders. You pass this context object to the Renderscript entry point class, so that - class can modify the rendering context if needed and bind the Renderscript code to the context. Once bound, - the view class can use the Renderscript code to display graphics. - The view class should also implement callbacks for events inherited from {@link - android.view.View}, such as {@link android.view.View#onTouchEvent onTouchEvent()} and {@link - android.view.View#onKeyDown onKeyDown()} if you want to detect these types of user interactions. - The SDK samples follow the convention of naming this file ActivityView.java, - where Activity is the name of your main activity class</dd> - - <dt>The activity <code>.java</code> class</dt> - - <dd>This class is the main activity class and sets your {@link android.renderscript.RSSurfaceView} as the main content - view for this activity or uses the {@link android.renderscript.RSTextureView} alongside other views.</dd> - </dl> - <p>Figure 1 describes how these classes interact with one another in a graphics Renderscript:</p> - - <img src="{@docRoot}images/rs_graphics.png"> - <p class="img-caption"><strong>Figure 1.</strong> Graphics Renderscript overview</p> - - - <p>The following sections describe how to create an application that uses a graphics Renderscript by using - the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Renderscript Fountain - sample</a> that is provided in the SDK as a guide (some code has been modified from its original - form for simplicity).</p> - - <h3 id="creating-native">Creating the Renderscript file</h3> - - <p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> (headers) files in the - <code><project_root>/src/</code> directory. This code contains the logic to render your - graphics and declares all other necessary items such as variables, structs, - and pointers. Every graphics <code>.rs</code> file generally contains the following items:</p> - - <ul> - <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) that declares - the package name of the <code>.java</code> reflection of this Renderscript.</li> - - <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of Renderscript that - you are using (1 is the only value for now).</li> - - <li>A <code>#include "rs_graphics.rsh"</code> declaration.</li> - - <li>A <code>root()</code> function. This is the main worker function for your Renderscript and - calls Renderscript graphics functions to render scenes. This function is called every time a - frame refresh occurs, which is specified as its return value. A <code>0</code> (zero) specified for - the return value says to only render the frame when a property of the scene that you are - rendering changes. A non-zero positive integer specifies the refresh rate of the frame in - milliseconds. - - <p class="note"><strong>Note:</strong> The Renderscript runtime makes its best effort to - refresh the frame at the specified rate. For example, if you are creating a live wallpaper - and set the return value to 20, the Renderscript runtime renders the wallpaper at 50fps if it has just - enough or more resources to do so. It renders as fast as it can if not enough resources - are available.</p> - - <p>For more information on using the Renderscript graphics functions, see the <a href= - "#drawing">Drawing</a> section.</p> - </li> - - <li>An <code>init()</code> function. This allows you to do initialization of your - Renderscript before the <code>root()</code> function runs, such as assigning values to variables. This - function runs once and is called automatically when the Renderscript starts, before anything - else in your Renderscript. Creating this function is optional.</li> - - <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can - be declared in <code>.rsh</code> files if desired)</li> - </ul> - - <p>The following code shows how the <code>fountain.rs</code> file is implemented:</p> - <pre> -#pragma version(1) - -// Tell which java package name the reflected files should belong to -#pragma rs java_package_name(com.example.android.rs.fountain) - -//declare shader binding -#pragma stateFragment(parent) - -// header with graphics APIs, must include explicitly -#include "rs_graphics.rsh" - -static int newPart = 0; - -// the mesh to render -rs_mesh partMesh; - -// the point representing where a particle is rendered -typedef struct __attribute__((packed, aligned(4))) Point { - float2 delta; - float2 position; - uchar4 color; -} Point_t; -Point_t *point; - -// main worker function that renders particles onto the screen -int root() { - float dt = min(rsGetDt(), 0.1f); - rsgClearColor(0.f, 0.f, 0.f, 1.f); - const float height = rsgGetHeight(); - const int size = rsAllocationGetDimX(rsGetAllocation(point)); - float dy2 = dt * (10.f); - Point_t * p = point; - for (int ct=0; ct < size; ct++) { - p->delta.y += dy2; - p->position += p->delta; - if ((p->position.y > height) && (p->delta.y > 0)) { - p->delta.y *= -0.3f; - } - p++; - } - - rsgDrawMesh(partMesh); - return 1; -} - -// adds particles to the screen to render -static float4 partColor[10]; -void addParticles(int rate, float x, float y, int index, bool newColor) -{ - if (newColor) { - partColor[index].x = rsRand(0.5f, 1.0f); - partColor[index].y = rsRand(1.0f); - partColor[index].z = rsRand(1.0f); - } - float rMax = ((float)rate) * 0.02f; - int size = rsAllocationGetDimX(rsGetAllocation(point)); - uchar4 c = rsPackColorTo8888(partColor[index]); - - Point_t * np = &point[newPart]; - float2 p = {x, y}; - while (rate--) { - float angle = rsRand(3.14f * 2.f); - float len = rsRand(rMax); - np->delta.x = len * sin(angle); - np->delta.y = len * cos(angle); - np->position = p; - np->color = c; - newPart++; - np++; - if (newPart >= size) { - newPart = 0; - np = &point[newPart]; - } - } -} -</pre> - - <h3 id="creating-entry">Creating the Renderscript entry point class</h3> - - <p>When you create a Renderscript (<code>.rs</code>) file, it is helpful to create a - corresponding Android framework class that is an entry point into the <code>.rs</code> file. - The most important thing this class does is receive a {@link android.renderscript.RenderScriptGL} rendering context - object from the <a href="#creating-view">view class</a> and binds the actual Renderscript - code to the rendering context. This notifies your view class of the code that it needs - to render graphics. - </p> - - <p>In addition, this class should contain all of the things needed to set up Renderscript. - Some important things that you need to do in this class are:</p> - - <ul> - <li>Create a Renderscript object - <code>ScriptC_<em>rs_filename</em></code>. The Renderscript object is attached to the Renderscript bytecode, which is platform-independent and - gets compiled on the device when the Renderscript application runs. The bytecode is referenced - as a raw resource and is passed into the constructor for the Renderscript object. - For example, this is how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> - sample creates the Renderscript object: - <pre> - RenderScriptGL rs; //obtained from the view class - Resources res; //obtained from the view class - ... - ScriptC_fountain mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); - </pre> - </li> - <li>Allocate any necessary memory and bind it to your Renderscript code via the Renderscript object.</li> - <li>Build any necessary meshes and bind them to the Renderscript code via the Renderscript object.</li> - <li>Create any necessary programs and bind them to the Renderscript code via the Renderscript object.</li> - </ul> - - <p>The following code shows how the <a href= - "{@docRoot}resources/samples/RenderScript/Fountain/src/com/example/android/rs/fountain/FountainRS.html"> - FountainRS</a> class is implemented:</p> - <pre> -package com.example.android.rs.fountain; - -import android.content.res.Resources; -import android.renderscript.*; -import android.util.Log; - -public class FountainRS { - public static final int PART_COUNT = 50000; - - public FountainRS() { - } - - /** - * This provides us with the Renderscript context and resources - * that allow us to create the Renderscript object - */ - private Resources mRes; - private RenderScriptGL mRS; - - // Renderscript object - private ScriptC_fountain mScript; - - // Called by the view class to initialize the Renderscript context and renderer - public void init(RenderScriptGL rs, Resources res) { - mRS = rs; - mRes = res; - - /** - * Create a shader and bind to the Renderscript context - */ - ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); - pfb.setVaryingColor(true); - rs.bindProgramFragment(pfb.create()); - - /** - * Allocate memory for the particles to render and create the mesh to draw - */ - ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); - Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); - smb.addVertexAllocation(points.getAllocation()); - smb.addIndexSetType(Mesh.Primitive.POINT); - Mesh sm = smb.create(); - - /** - * Create and bind the Renderscript object to the Renderscript context - */ - mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); - mScript.set_partMesh(sm); - mScript.bind_point(points); - mRS.bindRootScript(mScript); - } - - boolean holdingColor[] = new boolean[10]; - - /** - * Calls Renderscript functions (invoke_addParticles) - * via the Renderscript object to add particles to render - * based on where a user touches the screen. - */ - public void newTouchPosition(float x, float y, float pressure, int id) { - if (id >= holdingColor.length) { - return; - } - int rate = (int)(pressure * pressure * 500.f); - if (rate > 500) { - rate = 500; - } - if (rate > 0) { - mScript.invoke_addParticles(rate, x, y, id, !holdingColor[id]); - holdingColor[id] = true; - } else { - holdingColor[id] = false; - } - - } -} -</pre> - - - <h3 id="creating-view">Creating the view class</h3> - - - <p>To display graphics, you need a view to render on. Create a class that extends {@link - android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. This class - allows you to create a {@link android.renderscript.RenderScriptGL} context object by calling and - pass it to the Rendscript entry point class to bind the two. Once bound, the content is aware - of the code that it needs to use to render graphics with. If your Renderscript code - depends on any type of information that the view is aware of, such as touches from the user, - you can also use this class to relay that information to the Renderscript entry point class. - The following code shows how the <code>FountainView</code> class is implemented:</p> - <pre> -package com.example.android.rs.fountain; - -import android.renderscript.RSTextureView; -import android.renderscript.RenderScriptGL; -import android.content.Context; -import android.view.MotionEvent; - -public class FountainView extends RSTextureView { - - public FountainView(Context context) { - super(context); - } - // Renderscript context - private RenderScriptGL mRS; - // Renderscript entry point object that calls Renderscript code - private FountainRS mRender; - - /** - * Create Renderscript context and initialize Renderscript entry point - */ - @Override - protected void onAttachedToWindow() { - super.onAttachedToWindow(); - android.util.Log.e("rs", "onAttachedToWindow"); - if (mRS == null) { - RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig(); - mRS = createRenderScriptGL(sc); - mRender = new FountainRS(); - mRender.init(mRS, getResources()); - } - } - - @Override - protected void onDetachedFromWindow() { - super.onDetachedFromWindow(); - android.util.Log.e("rs", "onDetachedFromWindow"); - if (mRS != null) { - mRS = null; - destroyRenderScriptGL(); - } - } - - - /** - * Use callbacks to relay data to Renderscript entry point class - */ - @Override - public boolean onTouchEvent(MotionEvent ev) - { - int act = ev.getActionMasked(); - if (act == ev.ACTION_UP) { - mRender.newTouchPosition(0, 0, 0, ev.getPointerId(0)); - return false; - } else if (act == MotionEvent.ACTION_POINTER_UP) { - // only one pointer going up, we can get the index like this - int pointerIndex = ev.getActionIndex(); - int pointerId = ev.getPointerId(pointerIndex); - mRender.newTouchPosition(0, 0, 0, pointerId); - } - int count = ev.getHistorySize(); - int pcount = ev.getPointerCount(); - - for (int p=0; p < pcount; p++) { - int id = ev.getPointerId(p); - mRender.newTouchPosition(ev.getX(p), - ev.getY(p), - ev.getPressure(p), - id); - - for (int i=0; i < count; i++) { - mRender.newTouchPosition(ev.getHistoricalX(p, i), - ev.getHistoricalY(p, i), - ev.getHistoricalPressure(p, i), - id); - } - } - return true; - } -} -</pre> - - <h3 id="creating-activity">Creating the activity class</h3> - - <p>Applications that use Renderscript still behave like normal Android applications, so you - need an activity class that handles activity lifecycle callback events appropriately. The activity class - also sets your {@link android.renderscript.RSSurfaceView} view class to be the main content view of the - activity or uses your {@link android.renderscript.RSTextureView} - in a {@link android.view.ViewGroup} alongside other views.</p> - - <p>The following code shows how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> - sample declares its activity class:</p> - <pre> -package com.example.android.rs.fountain; - -import android.app.Activity; -import android.os.Bundle; -import android.util.Log; - -public class Fountain extends Activity { - - private static final String LOG_TAG = "libRS_jni"; - private static final boolean DEBUG = false; - private static final boolean LOG_ENABLED = false; - - private FountainView mView; - - @Override - public void onCreate(Bundle icicle) { - super.onCreate(icicle); - - // Create our Preview view and set it as - // the content of our activity - mView = new FountainView(this); - setContentView(mView); - } - - @Override - protected void onResume() { - Log.e("rs", "onResume"); - - // Ideally a game should implement onResume() and onPause() - // to take appropriate action when the activity looses focus - super.onResume(); - mView.resume(); - } - - @Override - protected void onPause() { - Log.e("rs", "onPause"); - - // Ideally a game should implement onResume() and onPause() - // to take appropriate action when the activity looses focus - super.onPause(); - mView.pause(); - - } - - static void log(String message) { - if (LOG_ENABLED) { - Log.v(LOG_TAG, message); - } - } -} -</pre> - -<p>Now that you have an idea of what is involved in a Renderscript graphics application, you can -start building your own. It might be easiest to begin with one of the -<a href="{@docRoot}resources/samples/RenderScript/index.html">Renderscript samples</a> as a starting -point if this is your first time using Renderscript.</p> - - <h2 id="drawing">Drawing</h2> - <p>The following sections describe how to use the graphics functions to draw with Renderscript.</p> - - <h3 id="drawing-rsg">Simple drawing</h3> - - <p>The native Renderscript APIs provide a few convenient functions to easily draw a polygon or text to - the screen. You call these in your <code>root()</code> function to have them render to the {@link - android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. These functions are - available for simple drawing and should not be used for complex graphics rendering:</p> - - <ul> - <li><code>rsgDrawRect()</code>: Sets up a mesh and draws a rectangle to the screen. It uses the - top left vertex and bottom right vertex of the rectangle to draw.</li> - - <li><code>rsgDrawQuad()</code>: Sets up a mesh and draws a quadrilateral to the screen.</li> - - <li><code>rsgDrawQuadTexCoords()</code>: Sets up a mesh and draws a quadrilateral to the screen - using the provided coordinates of a texture.</li> - - <li><code>rsgDrawText()</code>: Draws specified text to the screen. Use <code>rsgFontColor()</code> - to set the color of the text.</li> - </ul> - - <h3 id="drawing-mesh">Drawing with a mesh</h3> - - <p>When you want to render complex scenes to the screen, instantiate a {@link - android.renderscript.Mesh} and draw it with <code>rsgDrawMesh()</code>. A {@link - android.renderscript.Mesh} is a collection of allocations that represent vertex data (positions, - normals, texture coordinates) and index data that provides information on how to draw triangles - and lines with the provided vertex data. You can build a Mesh in three different ways:</p> - - <ul> - <li>Build the mesh with the {@link android.renderscript.Mesh.TriangleMeshBuilder} class, which - allows you to specify a set of vertices and indices for each triangle that you want to draw.</li> - - <li>Build the mesh using an {@link android.renderscript.Allocation} or a set of {@link - android.renderscript.Allocation}s with the {@link android.renderscript.Mesh.AllocationBuilder} - class. This approach allows you to build a mesh with vertices already stored in memory, which allows you - to specify the vertices in Renderscript or Android framework code.</li> - - <li>Build the mesh with the {@link android.renderscript.Mesh.Builder} class. You should use - this convenience method when you know the data types you want to use to build your mesh, but - don't want to make separate memory allocations like with {@link - android.renderscript.Mesh.AllocationBuilder}. You can specify the types that you want and this - mesh builder automatically creates the memory allocations for you.</li> - </ul> - - <p>To create a mesh using the {@link android.renderscript.Mesh.TriangleMeshBuilder}, you need to - supply it with a set of vertices and the indices for the vertices that comprise the triangle. For - example, the following code specifies three vertices, which are added to an internal array, - indexed in the order they were added. The call to {@link - android.renderscript.Mesh.TriangleMeshBuilder#addTriangle addTriangle()} draws the triangle with - vertex 0, 1, and 2 (the vertices are drawn counter-clockwise).</p> - <pre> -int float2VtxSize = 2; -Mesh.TriangleMeshBuilder triangles = new Mesh.TriangleMeshBuilder(renderscriptGL, -float2VtxSize, Mesh.TriangleMeshBuilder.COLOR); -triangles.addVertex(300.f, 300.f); -triangles.addVertex(150.f, 450.f); -triangles.addVertex(450.f, 450.f); -triangles.addTriangle(0 , 1, 2); -Mesh smP = triangle.create(true); -script.set_mesh(smP); -</pre> - - <p>To draw a mesh using the {@link android.renderscript.Mesh.AllocationBuilder}, you need to - supply it with one or more allocations that contain the vertex data:</p> - <pre> -Allocation vertices; - -... -Mesh.AllocationBuilder triangle = new Mesh.AllocationBuilder(mRS); -smb.addVertexAllocation(vertices.getAllocation()); -smb.addIndexSetType(Mesh.Primitive.TRIANGLE); -Mesh smP = smb.create(); -script.set_mesh(smP); -</pre> - - <p>In your Renderscript code, draw the built mesh to the screen:</p> - <pre> -rs_mesh mesh; -... - -int root(){ -... -rsgDrawMesh(mesh); -... -return 0; //specify a non zero, positive integer to specify the frame refresh. - //0 refreshes the frame only when the mesh changes. -} -</pre> - - <h2 id="shader">Programs</h2> - - <p>You can attach four program objects to the {@link android.renderscript.RenderScriptGL} context - to customize the rendering pipeline. For example, you can create vertex and fragment shaders in - GLSL or build a raster program object that controls culling. The four programs mirror a - traditional graphical rendering pipeline:</p> - - <table> - <tr> - <th>Android Object Type</th> - - <th>Renderscript Native Type</th> - - <th>Description</th> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramVertex}</td> - - <td>rs_program_vertex</td> - - <td> - <p>The Renderscript vertex program, also known as a vertex shader, describes the stage in - the graphics pipeline responsible for manipulating geometric data in a user-defined way. - The object is constructed by providing Renderscript with the following data:</p> - - <ul> - <li>An {@link android.renderscript.Element} describing its varying inputs or attributes</li> - - <li>GLSL shader string that defines the body of the program</li> - - <li>a {@link android.renderscript.Type} that describes the layout of an - Allocation containing constant or uniform inputs</li> - </ul> - - <p>Once the program is created, bind it to the {@link android.renderscript.RenderScriptGL} - graphics context by calling {@link android.renderscript.RenderScriptGL#bindProgramVertex - bindProgramVertex()}. It is then used for all subsequent draw calls until you bind a new - program. If the program has constant inputs, the user needs to bind an allocation - containing those inputs. The allocation's type must match the one provided during creation. - </p> - - <p>The Renderscript runtime then does all the necessary plumbing to send those constants to - the graphics hardware. Varying inputs to the shader, such as position, normal, and texture - coordinates are matched by name between the input {@link android.renderscript.Element} - and the mesh object that is being drawn. The signatures don't have to be exact or in any - strict order. As long as the input name in the shader matches a channel name and size - available on the mesh, the Renderscript runtime handles connecting the two. Unlike OpenGL - there is no need to link the vertex and fragment programs.</p> - - <p>To bind shader constants to the program, declare a <code>struct</code> that contains the necessary - shader constants in your Renderscript code. This <code>struct</code> is generated into a - reflected class that you can use as a constant input element during the program's creation. - It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then - bind this {@link android.renderscript.Allocation} to the program and the - Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware - when necessary. To update shader constants, you change the values in the - {@link android.renderscript.Allocation} and notify the Renderscript - code of the change.</p> - - <p>The {@link android.renderscript.ProgramVertexFixedFunction.Builder} class also - lets you build a simple vertex shader without writing GLSL code. - </p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramFragment}</td> - - <td>rs_program_fragment</td> - - <td> - <p>The Renderscript fragment program, also known as a fragment shader, is responsible for - manipulating pixel data in a user-defined way. It's constructed from a GLSL shader string - containing the program body, texture inputs, and a {@link android.renderscript.Type} - object that describes the constants - used by the program. Like the vertex programs, when an {@link android.renderscript.Allocation} - with constant input - values is bound to the shader, its values are sent to the graphics program automatically. - Note that the values inside the {@link android.renderscript.Allocation} are not explicitly tracked. - If they change between two draw calls using the same program object, notify the runtime of that change by - calling <code>rsgAllocationSyncAll()</code>, so it can send the new values to hardware. Communication - between the vertex and fragment programs is handled internally in the GLSL code. For - example, if the fragment program is expecting a varying input called <code>varTex0</code>, the GLSL code - inside the program vertex must provide it.</p> - - <p>To bind shader constructs to the program, declare a <code>struct</code> that contains the necessary - shader constants in your Renderscript code. This <code>struct</code> is generated into a - reflected class that you can use as a constant input element during the program's creation. - It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then - bind this {@link android.renderscript.Allocation} to the program and the - Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware - when necessary. To update shader constants, you change the values in the - {@link android.renderscript.Allocation} and notify the Renderscript - code of the change.</p> - - <p>The {@link android.renderscript.ProgramFragmentFixedFunction.Builder} class also - lets you build a simple fragment shader without writing GLSL code. - </p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramStore}</td> - - <td>rs_program_store</td> - - <td>The Renderscript store program contains a set of parameters that control how the graphics - hardware writes to the framebuffer. It could be used to enable and disable depth writes and - testing, setup various blending modes for effects like transparency and define write masks - for color components.</td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramRaster}</td> - - <td>rs_program_raster</td> - - <td>The Renderscript raster program is primarily used to specify whether point sprites are enabled and to - control the culling mode. By default back faces are culled.</td> - </tr> - </table> - - <p>The following example defines a vertex shader in GLSL and binds it to a Renderscript context object:</p> - <pre> - private RenderScriptGL glRenderer; //rendering context - private ScriptField_Point mPoints; //vertices - private ScriptField_VpConsts mVpConsts; //shader constants - - ... - - ProgramVertex.Builder sb = new ProgramVertex.Builder(glRenderer); - String t = "varying vec4 varColor;\n" + - "void main() {\n" + - " vec4 pos = vec4(0.0, 0.0, 0.0, 1.0);\n" + - " pos.xy = ATTRIB_position;\n" + - " gl_Position = UNI_MVP * pos;\n" + - " varColor = vec4(1.0, 1.0, 1.0, 1.0);\n" + - " gl_PointSize = ATTRIB_size;\n" + - "}\n"; - sb.setShader(t); - sb.addConstant(mVpConsts.getType()); - sb.addInput(mPoints.getElement()); - ProgramVertex pvs = sb.create(); - pvs.bindConstants(mVpConsts.getAllocation(), 0); - glRenderer.bindProgramVertex(pvs); -</pre> - - - <p>The <a href= - "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> - RsRenderStatesRS</a> sample has many examples on how to create a shader without writing GLSL.</p> - - <h3 id="shader-bindings">Program bindings</h3> - - <p>You can also declare four pragmas that control default program bindings to the {@link - android.renderscript.RenderScriptGL} context when the script is executing:</p> - - <ul> - <li><code>stateVertex</code></li> - - <li><code>stateFragment</code></li> - - <li><code>stateRaster</code></li> - - <li><code>stateStore</code></li> - </ul> - - <p>The possible values for each pragma are <code>parent</code> or <code>default</code>. Using - <code>default</code> binds the shaders to the graphical context with the system defaults.</p> - - <p>Using <code>parent</code> binds the shaders in the same manner as it is bound in the calling - script. If this is the root script, the parent state is taken from the bind points that are set - by the {@link android.renderscript.RenderScriptGL} bind methods.</p> - - <p>For example, you can define this at the top of your graphics Renderscript code to have - the vertex and store programs inherent the bind properties from their parent scripts:</p> - <pre> -#pragma stateVertex(parent) -#pragma stateStore(parent) -</pre> - - <h3 id="shader-sampler">Defining a sampler</h3> - - <p>A {@link android.renderscript.Sampler} object defines how data is extracted from textures. - Samplers are bound to a {@link android.renderscript.ProgramFragment} alongside the texture - whose sampling they control. These - objects are used to specify such things as edge clamping behavior, whether mip-maps are used, and - the amount of anisotropy required. There might be situations where hardware does not support the - desired behavior of the sampler. In these cases, the Renderscript runtime attempts to provide the - closest possible approximation. For example, the user requested 16x anisotropy, but only 8x was - set because it's the best available on the hardware.</p> - - <p>The <a href= - "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> - RsRenderStatesRS</a> sample has many examples on how to create a sampler and bind it to a - Fragment program.</p> - - - -<h2 id="fbo">Rendering to a Framebuffer Object</h2> - -<p>Framebuffer objects allow you to render offscreen instead of in the default onscreen -framebuffer. This approach might be useful for situations where you need to post-process a texture before -rendering it to the screen, or when you want to composite two scenes in one such as rendering a rear-view -mirror of a car. There are two buffers associated with a framebuffer object: a color buffer -and a depth buffer. The color buffer (required) contains the actual pixel data of the scene -that you are rendering, and the depth buffer (optional) contains the values necessary to figure -out what vertices are drawn depending on their z-values.</p> - -<p>In general, you need to do the following to render to a framebuffer object:</p> - -<ul> - <li>Create {@link android.renderscript.Allocation} objects for the color buffer and - depth buffer (if needed). Specify the {@link - android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} usage attribute for these - allocations to notify the Renderscript runtime to use these allocations for the framebuffer - object. For the color buffer allocation, you most likely need to declare the {@link - android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE} usage attribute - to use the color buffer as a texture, which is the most common use of the framebuffer object.</li> - - <li>Tell the Renderscript runtime to render to the framebuffer object instead of the default - framebuffer by calling <code>rsgBindColorTarget()</code> and passing it the color buffer - allocation. If applicable, call <code>rsgBindDepthTarget()</code> passing in the depth buffer - allocation as well.</li> - - <li>Render your scene normally with the <code>rsgDraw</code> functions. The scene will be - rendered into the color buffer instead of the default onscreen framebuffer.</li> - - <li>When done, tell the Renderscript runtime stop rendering to the color buffer and back - to the default framebuffer by calling <code>rsgClearAllRenderTargets()</code>.</li> - - <li>Create a fragment shader and bind a the color buffer to it as a texture.</li> - - <li>Render your scene to the default framebuffer. The texture will be used according - to the way you setup your fragment shader.</li> -</ul> - -<p>The following example shows you how to render to a framebuffer object by modifying the -<a href="{@docRoot}guide/resources/renderscript/Fountain/">Fountain</a> Renderscript sample. The end -result is the <a href="{@docRoot}guide/resources/renderscript/FountainFBO/">FountainFBO</a> sample. -The modifications render the exact same scene into a framebuffer object as it does the default -framebuffer. The framebuffer object is then rendered into the default framebuffer in a small -area at the top left corner of the screen.</p> - -<ol> - <li>Modify <code>fountain.rs</code> and add the following global variables. This creates setter - methods when this file is reflected into a <code>.java</code> file, allowing you to allocate - memory in your Android framework code and binding it to the Renderscript runtime. -<pre> -//allocation for color buffer -rs_allocation gColorBuffer; -//fragment shader for rendering without a texture (used for rendering to framebuffer object) -rs_program_fragment gProgramFragment; -//fragment shader for rendering with a texture (used for rendering to default framebuffer) -rs_program_fragment gTextureProgramFragment; -</pre> - </li> - - <li>Modify the root function of <code>fountain.rs</code> to look like the following code. The - modifications are commented: -<pre> -int root() { - float dt = min(rsGetDt(), 0.1f); - rsgClearColor(0.f, 0.f, 0.f, 1.f); - const float height = rsgGetHeight(); - const int size = rsAllocationGetDimX(rsGetAllocation(point)); - float dy2 = dt * (10.f); - Point_t * p = point; - for (int ct=0; ct < size; ct++) { - p->delta.y += dy2; - p->position += p->delta; - if ((p->position.y > height) && (p->delta.y > 0)) { - p->delta.y *= -0.3f; - } - p++; - } - //Tell Renderscript runtime to render to the frame buffer object - rsgBindColorTarget(gColorBuffer, 0); - //Begin rendering on a white background - rsgClearColor(1.f, 1.f, 1.f, 1.f); - rsgDrawMesh(partMesh); - - //When done, tell Renderscript runtime to stop rendering to framebuffer object - rsgClearAllRenderTargets(); - - //Bind a new fragment shader that declares the framebuffer object to be used as a texture - rsgBindProgramFragment(gTextureProgramFragment); - - //Bind the framebuffer object to the fragment shader at slot 0 as a texture - rsgBindTexture(gTextureProgramFragment, 0, gColorBuffer); - //Draw a quad using the framebuffer object as the texture - float startX = 10, startY = 10; - float s = 256; - rsgDrawQuadTexCoords(startX, startY, 0, 0, 1, - startX, startY + s, 0, 0, 0, - startX + s, startY + s, 0, 1, 0, - startX + s, startY, 0, 1, 1); - - //Rebind the original fragment shader to render as normal - rsgBindProgramFragment(gProgramFragment); - - //Render the main scene - rsgDrawMesh(partMesh); - - return 1; -} -</pre> - </li> - - <li>In the <code>FountainRS.java</code> file, modify the <code>init()</code> method to look - like the following code. The modifications are commented: - -<pre> -/* Add necessary members */ -private ScriptC_fountainfbo mScript; -private Allocation mColorBuffer; -private ProgramFragment mProgramFragment; -private ProgramFragment mTextureProgramFragment; - -public void init(RenderScriptGL rs, Resources res) { - mRS = rs; - mRes = res; - - ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); - - Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); - smb.addVertexAllocation(points.getAllocation()); - smb.addIndexSetType(Mesh.Primitive.POINT); - Mesh sm = smb.create(); - - mScript = new ScriptC_fountainfbo(mRS, mRes, R.raw.fountainfbo); - mScript.set_partMesh(sm); - mScript.bind_point(points); - - ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); - pfb.setVaryingColor(true); - mProgramFragment = pfb.create(); - mScript.set_gProgramFragment(mProgramFragment); - - /* Second fragment shader to use a texture (framebuffer object) to draw with */ - pfb.setTexture(ProgramFragmentFixedFunction.Builder.EnvMode.REPLACE, - ProgramFragmentFixedFunction.Builder.Format.RGBA, 0); - - /* Set the fragment shader in the Renderscript runtime */ - mTextureProgramFragment = pfb.create(); - mScript.set_gTextureProgramFragment(mTextureProgramFragment); - - /* Create the allocation for the color buffer */ - Type.Builder colorBuilder = new Type.Builder(mRS, Element.RGBA_8888(mRS)); - colorBuilder.setX(256).setY(256); - mColorBuffer = Allocation.createTyped(mRS, colorBuilder.create(), - Allocation.USAGE_GRAPHICS_TEXTURE | - Allocation.USAGE_GRAPHICS_RENDER_TARGET); - - /* Set the allocation in the Renderscript runtime */ - mScript.set_gColorBuffer(mColorBuffer); - - mRS.bindRootScript(mScript); -} -</pre> - -<p class="note"><strong>Note:</strong> This sample doesn't use a depth buffer, but the following code -shows you how to declare an example depth buffer if you need to use -one for your application. The depth buffer must have the same dimensions as the color buffer: - -<pre> -Allocation mDepthBuffer; - -... - -Type.Builder b = new Type.Builder(mRS, Element.createPixel(mRS, DataType.UNSIGNED_16, - DataKind.PIXEL_DEPTH)); -b.setX(256).setY(256); -mDepthBuffer = Allocation.createTyped(mRS, b.create(), -Allocation.USAGE_GRAPHICS_RENDER_TARGET); - -</pre> -</p> -</li> - - <li>Run and use the sample. The smaller, white quad on the top-left corner is using the - framebuffer object as a texture, which renders the same scene as the main rendering.</li> -</ol> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index c9f505f..8df1fdf 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -27,11 +27,13 @@ parent.link=manifest-intro.html android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 --> android:<a href="#prmsn">permission</a>="<i>string</i>" android:<a href="#proc">process</a>="<i>string</i>" - android:<a href="#screen">screenOrientation</a>=["unspecified" | "user" | "behind" | + android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" | "landscape" | "portrait" | "reverseLandscape" | "reversePortrait" | "sensorLandscape" | "sensorPortrait" | - "sensor" | "fullSensor" | "nosensor"] + "userLandscape" | "userPortrait" | + "sensor" | "fullSensor" | "nosensor" | + "user" | "fullUser" | "locked"] android:<a href="#state">stateNotNeeded</a>=["true" | "false"] android:<a href="#aff">taskAffinity</a>="<i>string</i>" android:<a href="#theme">theme</a>="<i>resource or theme</i>" @@ -52,85 +54,85 @@ parent.link=manifest-intro.html <br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> <dt>description:</dt> -<dd>Declares an activity (an {@link android.app.Activity} subclass) that -implements part of the application's visual user interface. All activities -must be represented by {@code <activity>} -elements in the manifest file. Any that are not declared there will not be seen +<dd>Declares an activity (an {@link android.app.Activity} subclass) that +implements part of the application's visual user interface. All activities +must be represented by {@code <activity>} +elements in the manifest file. Any that are not declared there will not be seen by the system and will never be run. <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> -<dd>Whether or not the activity can move from the task that started it to -the task it has an affinity for when that task is next brought to the -front — "{@code true}" if it can move, and "{@code false}" if it -must remain with the task where it started. +<dd>Whether or not the activity can move from the task that started it to +the task it has an affinity for when that task is next brought to the +front — "{@code true}" if it can move, and "{@code false}" if it +must remain with the task where it started. <p> -If this attribute is not set, the value set by the corresponding +If this attribute is not set, the value set by the corresponding <code><a href="{@docRoot}guide/topics/manifest/application-element.html#reparent">allowTaskReparenting</a></code> -attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element +attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element applies to the activity. The default value is "{@code false}". </p> <p> -Normally when an activity is started, it's associated with the task of -the activity that started it and it stays there for its entire lifetime. -You can use this attribute to force it to be re-parented to the task it -has an affinity for when its current task is no longer displayed. -Typically, it's used to cause the activities of an application to move +Normally when an activity is started, it's associated with the task of +the activity that started it and it stays there for its entire lifetime. +You can use this attribute to force it to be re-parented to the task it +has an affinity for when its current task is no longer displayed. +Typically, it's used to cause the activities of an application to move to the main task associated with that application. </p> <p> -For example, if an e-mail message contains a link to a web page, clicking -the link brings up an activity that can display the page. That activity -is defined by the browser application, but is launched as part of the e-mail -task. If it's reparented to the browser task, it will be shown when the -browser next comes to the front, and will be absent when the e-mail task +For example, if an e-mail message contains a link to a web page, clicking +the link brings up an activity that can display the page. That activity +is defined by the browser application, but is launched as part of the e-mail +task. If it's reparented to the browser task, it will be shown when the +browser next comes to the front, and will be absent when the e-mail task again comes forward. </p> <p> -The affinity of an activity is defined by the -<code><a href="#aff">taskAffinity</a></code> attribute. The affinity +The affinity of an activity is defined by the +<code><a href="#aff">taskAffinity</a></code> attribute. The affinity of a task is determined by reading the affinity of its root activity. Therefore, by definition, a root activity is always in a task with the -same affinity. Since activities with "{@code singleTask}" or +same affinity. Since activities with "{@code singleTask}" or "{@code singleInstance}" launch modes can only be at the root of a task, -re-parenting is limited to the "{@code standard}" and "{@code singleTop}" -modes. (See also the <code><a href="#lmode">launchMode</a></code> +re-parenting is limited to the "{@code standard}" and "{@code singleTop}" +modes. (See also the <code><a href="#lmode">launchMode</a></code> attribute.) </p></dd> <dt><a name="always"></a>{@code android:alwaysRetainTaskState}</dt> -<dd>Whether or not the state of the task that the activity is in will always -be maintained by the system — "{@code true}" if it will be, and -"{@code false}" if the system is allowed to reset the task to its initial -state in certain situations. The default value is "{@code false}". This -attribute is meaningful only for the root activity of a task; it's ignored +<dd>Whether or not the state of the task that the activity is in will always +be maintained by the system — "{@code true}" if it will be, and +"{@code false}" if the system is allowed to reset the task to its initial +state in certain situations. The default value is "{@code false}". This +attribute is meaningful only for the root activity of a task; it's ignored for all other activities. <p> -Normally, the system clears a task (removes all activities from the stack -above the root activity) in certain situations when the user re-selects that -task from the home screen. Typically, this is done if the user hasn't visited +Normally, the system clears a task (removes all activities from the stack +above the root activity) in certain situations when the user re-selects that +task from the home screen. Typically, this is done if the user hasn't visited the task for a certain amount of time, such as 30 minutes. </p> <p> -However, when this attribute is "{@code true}", users will always return -to the task in its last state, regardless of how they get there. This is -useful, for example, in an application like the web browser where there is +However, when this attribute is "{@code true}", users will always return +to the task in its last state, regardless of how they get there. This is +useful, for example, in an application like the web browser where there is a lot of state (such as multiple open tabs) that users would not like to lose. </p></dd> <dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt> -<dd>Whether or not all activities will be removed from the task, except for -the root activity, whenever it is re-launched from the home screen — -"{@code true}" if the task is always stripped down to its root activity, and -"{@code false}" if not. The default value is "{@code false}". This attribute -is meaningful only for activities that start a new task (the root activity); +<dd>Whether or not all activities will be removed from the task, except for +the root activity, whenever it is re-launched from the home screen — +"{@code true}" if the task is always stripped down to its root activity, and +"{@code false}" if not. The default value is "{@code false}". This attribute +is meaningful only for activities that start a new task (the root activity); it's ignored for all other activities in the task. <p> @@ -138,24 +140,24 @@ When the value is "{@code true}", every time users start the task again, they are brought to its root activity regardless of what they were last doing in the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to leave it. When the value is "{@code false}", the task may be cleared of activities in -some situations (see the -<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always. +some situations (see the +<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always. </p> <p> -Suppose, for example, that someone launches activity P from the home screen, -and from there goes to activity Q. The user next presses <em>Home</em>, and then returns -to activity P. Normally, the user would see activity Q, since that is what they -were last doing in P's task. However, if P set this flag to "{@code true}", all -of the activities on top of it (Q in this case) were removed when the user pressed -<em>Home</em> and the task went to the background. So the user sees only P when returning +Suppose, for example, that someone launches activity P from the home screen, +and from there goes to activity Q. The user next presses <em>Home</em>, and then returns +to activity P. Normally, the user would see activity Q, since that is what they +were last doing in P's task. However, if P set this flag to "{@code true}", all +of the activities on top of it (Q in this case) were removed when the user pressed +<em>Home</em> and the task went to the background. So the user sees only P when returning to the task. </p> <p> -If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code> -are both "{@code true}", any activities that can be re-parented are moved to -the task they share an affinity with; the remaining activities are then dropped, +If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code> +are both "{@code true}", any activities that can be re-parented are moved to +the task they share an affinity with; the remaining activities are then dropped, as described above. </p></dd> @@ -167,7 +169,7 @@ activity remains running and its <code>{@link android.app.Activity#onConfigurati onConfigurationChanged()}</code> method is called. <p class="note"><strong>Note:</strong> Using this attribute should be -avoided and used only as a last-resort. Please read <a +avoided and used only as a last resort. Please read <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a> for more information about how to properly handle a restart due to a configuration change.</p> @@ -218,11 +220,11 @@ separated by '{@code |}' — for example, "{@code locale|navigation|orientat <td>"{@code uiMode}"</td> <td>The user interface mode has changed — this can be caused when the user places the device into a desk/car dock or when the night mode changes. See {@link -android.app.UiModeManager}. +android.app.UiModeManager}. <em>Added in API level 8</em>.</td> </tr><tr> <td>"{@code orientation}"</td> - <td>The screen orientation has changed — the user has rotated the device. + <td>The screen orientation has changed — the user has rotated the device. <p class="note"><strong>Note:</strong> If your application targets API level 13 or higher (as declared by the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code @@ -256,70 +258,70 @@ restart your activity, even when running on an Android 3.2 or higher device). </table> <p> -All of these configuration changes can impact the resource values seen by the -application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged -onConfigurationChanged()}</code> is called, it will generally be necessary to again -retrieve all resources (including view layouts, drawables, and so on) to correctly -handle the change. +All of these configuration changes can impact the resource values seen by the +application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged +onConfigurationChanged()}</code> is called, it will generally be necessary to again +retrieve all resources (including view layouts, drawables, and so on) to correctly +handle the change. </p></dd> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the activity can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value +<dd>Whether or not the activity can be instantiated by the system — +"{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code true}". <p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> -attribute that applies to all application components, including activities. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -and {@code <activity>} attributes must both be "{@code true}" (as they both -are by default) for the system to be able to instantiate the activity. If either +The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> +attribute that applies to all application components, including activities. The +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +and {@code <activity>} attributes must both be "{@code true}" (as they both +are by default) for the system to be able to instantiate the activity. If either is "{@code false}", it cannot be instantiated. </p></dd> <dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt> <dd>Whether or not the task initiated by this activity should be excluded from the list of recently used applications ("recent apps"). That is, when this activity is the root activity of a new task, -this attribute determines whether the task should not appear in the list of recent apps. "{@code -true}" if the task should be <em>excluded</em> from the list; "{@code false}" if it should be +this attribute determines whether the task should not appear in the list of recent apps. Set "{@code +true}" if the task should be <em>excluded</em> from the list; set "{@code false}" if it should be <em>included</em>. The default value is "{@code false}". </p></dd> <dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not the activity can be launched by components of other -applications — "{@code true}" if it can be, and "{@code false}" if not. -If "{@code false}", the activity can be launched only by components of the -same application or applications with the same user ID. +<dd>Whether or not the activity can be launched by components of other +applications — "{@code true}" if it can be, and "{@code false}" if not. +If "{@code false}", the activity can be launched only by components of the +same application or applications with the same user ID. <p> -The default value depends on whether the activity contains intent filters. The -absence of any filters means that the activity can be invoked only by specifying -its exact class name. This implies that the activity is intended only for -application-internal use (since others would not know the class name). So in +The default value depends on whether the activity contains intent filters. The +absence of any filters means that the activity can be invoked only by specifying +its exact class name. This implies that the activity is intended only for +application-internal use (since others would not know the class name). So in this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the activity +On the other hand, the presence of at least one filter implies that the activity is intended for external use, so the default value is "{@code true}". </p> <p> This attribute is not the only way to limit an activity's exposure to other -applications. You can also use a permission to limit the external entities that -can invoke the activity (see the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code> +applications. You can also use a permission to limit the external entities that +can invoke the activity (see the +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code> attribute). </p></dd> <dt><a name="finish"></a>{@code android:finishOnTaskLaunch}</dt> -<dd>Whether or not an existing instance of the activity should be shut down -(finished) whenever the user again launches its task (chooses the task on the -home screen) — "{@code true}" if it should be shut down, and "{@code false}" +<dd>Whether or not an existing instance of the activity should be shut down +(finished) whenever the user again launches its task (chooses the task on the +home screen) — "{@code true}" if it should be shut down, and "{@code false}" if not. The default value is "{@code false}". <p> -If this attribute and -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -are both "{@code true}", this attribute trumps the other. The affinity of the +If this attribute and +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> +are both "{@code true}", this attribute trumps the other. The affinity of the activity is ignored. The activity is not re-parented, but destroyed. </p> @@ -344,58 +346,58 @@ make use of the renderer without errors.</p> </dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the activity. The icon is displayed to users when -a representation of the activity is required on-screen. For example, icons -for activities that initiate tasks are displayed in the launcher window. +<dd>An icon representing the activity. The icon is displayed to users when +a representation of the activity is required on-screen. For example, icons +for activities that initiate tasks are displayed in the launcher window. The icon is often accompanied by a label (see the <a href="#label">{@code android:label}</a> attribute). </p> <p> -This attribute must be set as a reference to a drawable resource containing -the image definition. If it is not set, the icon specified for the application -as a whole is used instead (see the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +This attribute must be set as a reference to a drawable resource containing +the image definition. If it is not set, the icon specified for the application +as a whole is used instead (see the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). </p> <p> -The activity's icon — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element — is also the default icon for all the activity's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). +The activity's icon — whether set here or by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +element — is also the default icon for all the activity's intent filters (see the +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). </p></dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the activity. The label is displayed on-screen -when the activity must be represented to the user. It's often displayed along +<dd>A user-readable label for the activity. The label is displayed on-screen +when the activity must be represented to the user. It's often displayed along with the activity icon. <p> -If this attribute is not set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +If this attribute is not set, the label set for the application as a whole is +used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). </p> <p> -The activity's label — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default label for all the activity's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). +The activity's label — whether set here or by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the +default label for all the activity's intent filters (see the +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). </p> <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="lmode"></a>{@code android:launchMode}</dt> <dd>An instruction on how the activity should be launched. There are four modes -that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) +that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) in {@link android.content.Intent} objects to determine what should happen when the activity is called upon to handle an intent. They are:</p> @@ -415,7 +417,7 @@ As shown in the table below, the modes fall into two main groups, with An activity with the "{@code standard}" or "{@code singleTop}" launch mode can be instantiated multiple times. The instances can belong to any task and can be located anywhere in the activity stack. Typically, they're -launched into the task that called +launched into the task that called <code>{@link android.content.Context#startActivity startActivity()}</code> (unless the Intent object contains a <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> @@ -431,7 +433,7 @@ Moreover, the device can hold only one instance of the activity at a time </p> <p> -The "{@code standard}" and "{@code singleTop}" modes differ from each other +The "{@code standard}" and "{@code singleTop}" modes differ from each other in just one respect: Every time there's a new intent for a "{@code standard}" activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. @@ -507,41 +509,41 @@ common and useful launch mode for many types of activities. The other modes — <code>singleTask</code> and <code>singleInstance</code> — are <span style="color:red">not appropriate for most applications</span>, since they result in an interaction model that is likely to be unfamiliar to -users and is very different from most other applications. +users and is very different from most other applications. <p>Regardless of the launch mode that you choose, make sure to test the usability of the activity during launch and when navigating back to it from other activities and tasks using the <em>Back</em> button. </p> <p>For more information on launch modes and their interaction with Intent -flags, see the +flags, see the <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> document. </p> </dd> <dt><a name="multi"></a>{@code android:multiprocess}</dt> -<dd>Whether an instance of the activity can be launched into the process of the component -that started it — "{@code true}" if it can be, and "{@code false}" if not. +<dd>Whether an instance of the activity can be launched into the process of the component +that started it — "{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code false}". <p> -Normally, a new instance of an activity is launched into the process of the -application that defined it, so all instances of the activity run in the same -process. However, if this flag is set to "{@code true}", instances of the -activity can run in multiple processes, allowing the system to create instances -wherever they are used (provided permissions allow it), something that is almost +Normally, a new instance of an activity is launched into the process of the +application that defined it, so all instances of the activity run in the same +process. However, if this flag is set to "{@code true}", instances of the +activity can run in multiple processes, allowing the system to create instances +wherever they are used (provided permissions allow it), something that is almost never necessary or desirable. </p></dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the class that implements the activity, a subclass of -{@link android.app.Activity}. The attribute value should be a fully qualified -class name (such as, "{@code com.example.project.ExtracurricularActivity}"). -However, as a shorthand, if the first character of the name is a period -(for example, "{@code .ExtracurricularActivity}"), it is appended to the -package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> +<dd>The name of the class that implements the activity, a subclass of +{@link android.app.Activity}. The attribute value should be a fully qualified +class name (such as, "{@code com.example.project.ExtracurricularActivity}"). +However, as a shorthand, if the first character of the name is a period +(for example, "{@code .ExtracurricularActivity}"), it is appended to the +package name specified in the +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p>Once you publish your application, you <a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not @@ -555,9 +557,9 @@ There is no default. The name must be specified. <!-- ##api level 3## --> <dt><a name="nohist"></a>{@code android:noHistory}</dt> <dd>Whether or not the activity should be removed from the activity stack and -finished (its <code>{@link android.app.Activity#finish finish()}</code> -method called) when the user navigates away from it and it's no longer -visible on screen — "{@code true}" if it should be finished, and +finished (its <code>{@link android.app.Activity#finish finish()}</code> +method called) when the user navigates away from it and it's no longer +visible on screen — "{@code true}" if it should be finished, and "{@code false}" if not. The default value is "{@code false}". <p> @@ -573,14 +575,33 @@ This attribute was introduced in API Level 3. <!-- api level 16 --> <dt><a name="parent"></a>{@code android:parentActivityName}</dt> -<dd>The class name of the logical parent of the activity. The name here must be formatted - the same as the corresponding activity is declared in its own - <a href="#nm">android:name</a>. - +<dd>The class name of the logical parent of the activity. The name here must match the class + name given to the corresponding {@code <activity>} element's + <a href="#nm"><code>android:name</code></a> attribute. + <p>The system reads this attribute to determine which activity should be started when the use presses the Up button in the action bar. The system can also use this information to synthesize a back stack of activities with {@link android.app.TaskStackBuilder}.</p> +<p>To support API levels 4 - 16, you can also declare the parent activity with a {@code +<meta-data>} element that specifies a value for {@code "android.support.PARENT_ACTIVITY"}. +For example:</p> +<pre> +<activity + android:name="com.example.app.ChildActivity" + android:label="@string/title_child_activity" + android:parentActivityName="com.example.myfirstapp.MainActivity" > + <!-- Parent activity meta-data to support API level 4+ --> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value="com.example.app.MainActivity" /> +</activity> +</pre> + +<p>For more information about declaring the parent activity to support Up navigation, +read <a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up +Navigation</a>.</p> + <p> This attribute was introduced in API Level 16. </p> @@ -589,66 +610,67 @@ This attribute was introduced in API Level 16. <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have to launch the activity -or otherwise get it to respond to an intent. If a caller of +<dd>The name of a permission that clients must have to launch the activity +or otherwise get it to respond to an intent. If a caller of <code>{@link android.content.Context#startActivity startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code> -has not been granted the specified permission, its intent will not be +has not been granted the specified permission, its intent will not be delivered to the activity. <p> -If this attribute is not set, the permission set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +If this attribute is not set, the permission set by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies to the activity. If neither attribute is set, the activity is not protected by a permission. </p> <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and another document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> +section in the introduction and another document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the activity should run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> -attribute can set a different default for all components. But each component -can override the default, allowing you to spread your application across +<dd>The name of the process in which the activity should run. Normally, all components of an +application run in a default process name created for the application and you do +not need to use this attribute. But if necessary, you can override the default process +name with this attribute, allowing you to spread your app components across multiple processes. <p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and +If the name assigned to this attribute begins with a colon (':'), a new +process, private to the application, is created when it's needed and the activity runs in that process. -If the process name begins with a lowercase character, the activity will run +If the process name begins with a lowercase character, the activity will run in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing +This allows components in different applications to share a process, reducing resource usage. -</p></dd> +</p> + +<p>The <code><a href="{@docRoot}guide/topics/manifest/application-element.html" +><application></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> +attribute can set a different default process name for all components. +</dd> <dt><a name="screen"></a>{@code android:screenOrientation}</dt> -<dd>The orientation of the activity's display on the device. - +<dd>The orientation of the activity's display on the device. + <p>The value can be any one of the following strings:</p> <table> <tr> <td>"{@code unspecified}"</td> <td>The default value. The system chooses the orientation. The policy it - uses, and therefore the choices made in specific contexts, may differ + uses, and therefore the choices made in specific contexts, may differ from device to device.</td> </tr><tr> - <td>"{@code user}"</td> - <td>The user's current preferred orientation.</td> -</tr><tr> <td>"{@code behind}"</td> - <td>The same orientation as the activity that's immediately beneath it in + <td>The same orientation as the activity that's immediately beneath it in the activity stack.</td> </tr><tr> <td>"{@code landscape}"</td> @@ -675,6 +697,18 @@ sensor. sensor. <em>Added in API level 9.</em></td> </tr><tr> + <td>"{@code userLandscape}"</td> + <td>Landscape orientation, but can be either normal or reverse landscape based on the device +sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves +the same as {@code landscape}, otherwise it behaves the same as {@code sensorLandscape}. +<em>Added in API level 18.</em></td> +</tr><tr> + <td>"{@code userPortrait}"</td> + <td>Portrait orientation, but can be either normal or reverse portrait based on the device +sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves +the same as {@code portrait}, otherwise it behaves the same as {@code sensorPortrait}. +<em>Added in API level 18.</em></td> +</tr><tr> <td>"{@code sensor}"</td> <td>The orientation is determined by the device orientation sensor. The orientation of the display depends on how the user is holding the device; it changes when the user rotates the @@ -692,6 +726,19 @@ portrait or reverse landscape, but this enables those). <em>Added in API level 9 is ignored, so the display will not rotate based on how the user moves the device. Except for this distinction, the system chooses the orientation using the same policy as for the "{@code unspecified}" setting.</td> +</tr><tr> + <td>"{@code user}"</td> + <td>The user's current preferred orientation.</td> +</tr><tr> + <td>"{@code fullUser}"</td> + <td>If the user has locked sensor-based rotation, this behaves the same as {@code user}, + otherwise it behaves the same as {@code fullSensor} and allows any of the 4 possible + screen orientations. + <em>Added in API level 18.</em></td> +</tr><tr> + <td>"{@code locked}"</td> + <td>Locks the orientation to its current rotation, whatever that is. +<em>Added in API level 18.</em></td> </tr> </table> @@ -712,76 +759,76 @@ control whether your app can be installed when a device supports only certain or </dd> <dt><a name="state"></a>{@code android:stateNotNeeded}</dt> -<dd>Whether or not the activity can be killed and successfully restarted -without having saved its state — "{@code true}" if it can be restarted -without reference to its previous state, and "{@code false}" if its previous +<dd>Whether or not the activity can be killed and successfully restarted +without having saved its state — "{@code true}" if it can be restarted +without reference to its previous state, and "{@code false}" if its previous state is required. The default value is "{@code false}". <p> -Normally, before an activity is temporarily shut down to save resources, its -<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code> -method is called. This method stores the current state of the activity in a -{@link android.os.Bundle} object, which is then passed to -<code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity -is restarted. If this attribute is set to "{@code true}", -{@code onSaveInstanceState()} may not be called and {@code onCreate()} will -be passed {@code null} instead of the Bundle — just as it was when the +Normally, before an activity is temporarily shut down to save resources, its +<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code> +method is called. This method stores the current state of the activity in a +{@link android.os.Bundle} object, which is then passed to +<code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity +is restarted. If this attribute is set to "{@code true}", +{@code onSaveInstanceState()} may not be called and {@code onCreate()} will +be passed {@code null} instead of the Bundle — just as it was when the activity started for the first time. </p> <p> -A "{@code true}" setting ensures that the activity can be restarted in the -absence of retained state. For example, the activity that displays the -home screen uses this setting to make sure that it does not get removed if it +A "{@code true}" setting ensures that the activity can be restarted in the +absence of retained state. For example, the activity that displays the +home screen uses this setting to make sure that it does not get removed if it crashes for some reason. </p></dd> <dt><a name="aff"></a>{@code android:taskAffinity}</dt> -<dd>The task that the activity has an affinity for. Activities with +<dd>The task that the activity has an affinity for. Activities with the same affinity conceptually belong to the same task (to the same -"application" from the user's perspective). The affinity of a task -is determined by the affinity of its root activity. +"application" from the user's perspective). The affinity of a task +is determined by the affinity of its root activity. <p> -The affinity determines two things — the task that the activity is re-parented -to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute) and the task that will house the activity when it is launched -with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> +The affinity determines two things — the task that the activity is re-parented +to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> +attribute) and the task that will house the activity when it is launched +with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag. </p> <p> By default, all activities in an application have the same affinity. You can set this attribute to group them differently, and even place -activities defined in different applications within the same task. To +activities defined in different applications within the same task. To specify that the activity does not have an affinity for any task, set it to an empty string. <p> -If this attribute is not set, the activity inherits the affinity set -for the application (see the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's +If this attribute is not set, the activity inherits the affinity set +for the application (see the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code> -attribute). The name of the default affinity for an application is -the package name set by the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> +attribute). The name of the default affinity for an application is +the package name set by the +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. </p> <dt><a name="theme"></a>{@code android:theme}</dt> -<dd>A reference to a style resource defining an overall theme for the activity. +<dd>A reference to a style resource defining an overall theme for the activity. This automatically sets the activity's context to use this theme (see -<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also -cause "starting" animations prior to the activity being launched (to better +<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also +cause "starting" animations prior to the activity being launched (to better match what the activity actually looks like). <p> -If this attribute is not set, the activity inherits the theme set for the -application as a whole — from the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code> +If this attribute is not set, the activity inherits the theme set for the +application as a whole — from the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +element's +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code> attribute. If that attribute is also not set, the default system theme is used. For more information, see the <a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. @@ -813,32 +860,32 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.< <!-- ##api level 3## --> <dt><a name="wsoft"></a>{@code android:windowSoftInputMode}</dt> -<dd>How the main window of the activity interacts with the window containing -the on-screen soft keyboard. The setting for this attribute affects two -things: +<dd>How the main window of the activity interacts with the window containing +the on-screen soft keyboard. The setting for this attribute affects two +things: -<ul> -<li>The state of the soft keyboard — whether it is hidden or visible +<ul> +<li>The state of the soft keyboard — whether it is hidden or visible — when the activity becomes the focus of user attention.</li> -<li>The adjustment made to the activity's main window — whether it is -resized smaller to make room for the soft keyboard or whether its contents -pan to make the current focus visible when part of the window is covered by +<li>The adjustment made to the activity's main window — whether it is +resized smaller to make room for the soft keyboard or whether its contents +pan to make the current focus visible when part of the window is covered by the soft keyboard.</li> </ul> <p> -The setting must be one of the values listed in the following table, or a -combination of one "{@code state...}" value plus one "{@code adjust...}" -value. Setting multiple values in either group — multiple -"{@code state...}" values, for example — has undefined results. +The setting must be one of the values listed in the following table, or a +combination of one "{@code state...}" value plus one "{@code adjust...}" +value. Setting multiple values in either group — multiple +"{@code state...}" values, for example — has undefined results. Individual values are separated by a vertical bar ({@code |}). For example: </p> <pre><activity android:windowSoftInputMode="stateVisible|adjustResize" . . . ></pre> <p> -Values set here (other than "{@code stateUnspecified}" and +Values set here (other than "{@code stateUnspecified}" and "{@code adjustUnspecified}") override values set in the theme. </p> @@ -848,9 +895,9 @@ Values set here (other than "{@code stateUnspecified}" and <th>Description</th> </tr><tr> <td>"{@code stateUnspecified}"</td> - <td>The state of the soft keyboard (whether it is hidden or visible) + <td>The state of the soft keyboard (whether it is hidden or visible) is not specified. The system will choose an appropriate state or - rely on the setting in the theme. + rely on the setting in the theme. <p> This is the default setting for the behavior of the soft keyboard. @@ -861,32 +908,32 @@ Values set here (other than "{@code stateUnspecified}" and whether visible or hidden, when the activity comes to the fore.</td> </tr></tr> <td>"{@code stateHidden}"</td> - <td>The soft keyboard is hidden when the user chooses the activity - — that is, when the user affirmatively navigates forward to the + <td>The soft keyboard is hidden when the user chooses the activity + — that is, when the user affirmatively navigates forward to the activity, rather than backs into it because of leaving another activity.</td> </tr></tr> <td>"{@code stateAlwaysHidden}"</td> - <td>The soft keyboard is always hidden when the activity's main window + <td>The soft keyboard is always hidden when the activity's main window has input focus.</td> </tr></tr> <td>"{@code stateVisible}"</td> - <td>The soft keyboard is visible when that's normally appropriate + <td>The soft keyboard is visible when that's normally appropriate (when the user is navigating forward to the activity's main window).</td> </tr></tr> <td>"{@code stateAlwaysVisible}"</td> - <td>The soft keyboard is made visible when the user chooses the - activity — that is, when the user affirmatively navigates forward - to the activity, rather than backs into it because of leaving another + <td>The soft keyboard is made visible when the user chooses the + activity — that is, when the user affirmatively navigates forward + to the activity, rather than backs into it because of leaving another activity.</td> </tr></tr> <td>"{@code adjustUnspecified}"</td> - <td>It is unspecified whether the activity's main window resizes - to make room for the soft keyboard, or whether the contents - of the window pan to make the currentfocus visible on-screen. + <td>It is unspecified whether the activity's main window resizes + to make room for the soft keyboard, or whether the contents + of the window pan to make the current focus visible on-screen. The system will automatically select one of these modes depending - on whether the content of the window has any layout views that - can scroll their contents. If there is such a view, the window - will be resized, on the assumption that scrolling can make all + on whether the content of the window has any layout views that + can scroll their contents. If there is such a view, the window + will be resized, on the assumption that scrolling can make all of the window's contents visible within a smaller area. <p> @@ -894,14 +941,14 @@ Values set here (other than "{@code stateUnspecified}" and </p></td> </tr></tr> <td>"{@code adjustResize}"</td> - <td>The activity's main window is always resized to make room for + <td>The activity's main window is always resized to make room for the soft keyboard on screen.</td> </tr></tr> <td>"{@code adjustPan}"</td> <td>The activity's main window is not resized to make room for the soft - keyboard. Rather, the contents of the window are automatically + keyboard. Rather, the contents of the window are automatically panned so that the current focus is never obscured by the keyboard - and users can always see what they are typing. This is generally less + and users can always see what they are typing. This is generally less desirable than resizing, because the user may need to close the soft keyboard to get at and interact with obscured parts of the window.</td> </tr> @@ -914,12 +961,12 @@ This attribute was introduced in API Level 3. <!-- ##api level indication## --> <dt>introduced in:</dt> -<dd>API Level 1 for all attributes except for +<dd>API Level 1 for all attributes except for <code><a href="#nohist">noHistory</a></code> and -<code><a href="#wsoft">windowSoftInputMode</a></code>, which were added in API +<code><a href="#wsoft">windowSoftInputMode</a></code>, which were added in API Level 3.</dd> <dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> <br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code></dd> </dl> diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 42cfdd5..6bfa3dc 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -1,11 +1,11 @@ page.title=<application> -parent.title=The AndroidManifest.xml File -parent.link=manifest-intro.html + @jd:body <dl class="xml"> <dt>syntax:</dt> <dd><pre class="stx"><application android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] + android:<a href="#allowbackup">allowBackup</a>=["true" | "false"] android:<a href="#agent">backupAgent</a>="<i>string</i>" android:<a href="#debug">debuggable</a>=["true" | "false"] android:<a href="#desc">description</a>="<i>string resource</i>" @@ -23,10 +23,14 @@ parent.link=manifest-intro.html android:<a href="#persistent">persistent</a>=["true" | "false"] android:<a href="#proc">process</a>="<i>string</i>" android:<a href="#restoreany">restoreAnyVersion</a>=["true" | "false"] + android:<a href="#requiredAccountType">requiredAccountType</a>="<i>string</i>" + android:<a href="#restrictedAccountType">restrictedAccountType</a>="<i>string</i>" android:<a href="#supportsrtl">supportsRtl</a>=["true" | "false"] android:<a href="#aff">taskAffinity</a>="<i>string</i>" + android:<a href="#testOnly">testOnly</a>=["true" | "false"] android:<a href="#theme">theme</a>="<i>resource or theme</i>" - android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"] > + android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"] + android:<a href="#vmSafeMode">vmSafeMode</a>=["true" | "false"] > . . . </application></pre></dd> @@ -52,6 +56,10 @@ for corresponding attributes of the component elements. Others (such as {@code allowClearUserData}) set values for the application as a whole and cannot be overridden by the components.</dd> + + + + <dt>attributes</dt> <dd><dl class="attr"> @@ -71,6 +79,15 @@ attribute that can override the value set here. See that attribute for more information. </p></dd> + +<dt><a name="allowbackup"></a>{@code android:allowbackup}</dt> +<dd>Whether to allow the application to participate in the backup +and restore infrastructure. If this attribute is set to false, no backup +or restore of the application will ever be performed, even by a full-system +backup that would otherwise cause all application data to be saved via adb. +The default value of this attribute is true.</dd> + + <dt><a name="agent"></a>{@code android:backupAgent}</dt> <dd>The name of the class that implement's the application's backup agent, a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be @@ -282,6 +299,57 @@ incompatible. <em>Use with caution!</em> <p>The default value of this attribute is {@code false}. </p></dd> + + +<dt><a name="requiredAccountType"></a>{@code android:requiredAccountType}</dt> +<dd>Specifies the account type required by the application in order to function. +If your app requires an {@link android.accounts.Account}, the value for this attribute must +correspond to the account authenticator +type used by your app (as defined by {@link android.accounts.AuthenticatorDescription}), +such as "com.google". + +<p>The default value is null and indicates that the application +can work <em>without</em> any accounts. + +<p>Because restricted profiles currently +cannot add accounts, specifying this attribute <strong>makes your app +unavailable from a restricted profile</strong> unless you also declare +<a href="#restrictedAccountType">{@code android:restrictedAccountType}</a> with +the same value.</p> + +<p class="caution"><strong>Caution:</strong> +If the account data may reveal personally identifiable information, it's important +that you declare this attribute and leave <a href="#restrictedAccountType">{@code android:restrictedAccountType}</a> null, so that restricted profiles cannot use +your app to access personal information that belongs to the owner user.</p> + +<p>This attribute was added in API level 18.</p> +</dd> + + +<dt><a name="restrictedAccountType"></a>{@code android:restrictedAccountType}</dt> +<dd>Specifies the account type required by this application and indicates that restricted profiles +are allowed to access such accounts that belong to the owner user. If your app requires an +{@link android.accounts.Account} and restricted profiles <strong>are allowed to +access</strong> the primary user's accounts, the value for this attribute must +correspond to the account authenticator type used by your app (as +defined by {@link android.accounts.AuthenticatorDescription}), such as "com.google". + +<p>The default value is null and indicates that the application can work <em>without</em> any +accounts. + +<p class="caution"><strong>Caution:</strong> +Specifying this attribute allows restricted profiles to use your +app with accounts that belong to the owner user, which may reveal personally identifiable +information. If the account may reveal personal details, you <strong>should not</strong> +use this attribute and you should instead declare the <a +href="#requiredAccountType">{@code android:requiredAccountType}</a> attribute +to make your app unavailable to restricted profiles.</p> + +<p>This attribute was added in API level 18.</p> +</dd> + + + <dt><a name="supportsrtl"></a>{@code android:supportsRtl}</dt> <dd>Declares whether your application is willing to support right-to-left (RTL) layouts. <p>If set to {@code true} and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" @@ -310,6 +378,13 @@ set by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. </p></dd> +<dt><a name="testOnly"></a>{@code android:testOnly}</dt> +<dd>Indicates whether this application is only for testing purposes. For example, +it may expose functionality or data outside of itself that would cause a security +hole, but is useful for testing. This kind of application can be installed +only through adb.</dd> + + <dt><a name="theme"></a>{@code android:theme}</dt> <dd>A reference to a style resource defining a default theme for all activities in the application. Individual activities can override @@ -340,6 +415,14 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.< <p>This attribute was added in API level 14.</p> </dd> +<dt><a name="vmSafeMode"></a>{@code android:vmSafeMode}</dt> +<dd>Indicates whether the app would like the virtual machine (VM) to operate +in safe mode. The default value is {@code "false"}. +</dd> + + + + </dl></dd> <!-- ##api level indication## --> diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index d5b5bdf..18e479f 100644 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd @@ -1,4 +1,4 @@ -page.title=<uses-sdk> +fpage.title=<uses-sdk> page.tags="api levels","sdk version","minsdkversion","targetsdkversion","maxsdkversion" @jd:body @@ -227,16 +227,22 @@ Versions dashboards page</a>.</p> <table> <tr><th>Platform Version</th><th>API Level</th><th>VERSION_CODE</th><th>Notes</th></tr> + <tr><td><a href="{@docRoot}about/versions/android-4.3.html">Android 4.3</a></td> + <td><a href="{@docRoot}sdk/api_diff/18/changes.html" title="Diff Report">18</a></td> + <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2}</td> + <td><a href="{@docRoot}about/versions/jelly-bean.html">Platform +Highlights</a></td></tr> + <tr><td><a href="{@docRoot}about/versions/android-4.2.html">Android 4.2, 4.2.2</a></td> <td><a href="{@docRoot}sdk/api_diff/17/changes.html" title="Diff Report">17</a></td> <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1}</td> - <td><a href="{@docRoot}about/versions/jelly-bean.html">Platform + <td><a href="{@docRoot}about/versions/jelly-bean.html#android-42">Platform Highlights</a></td></tr> <tr><td><a href="{@docRoot}about/versions/android-4.1.html">Android 4.1, 4.1.1</a></td> <td><a href="{@docRoot}sdk/api_diff/16/changes.html" title="Diff Report">16</a></td> <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN}</td> - <td><a href="{@docRoot}about/versions/jelly-bean.html">Platform + <td><a href="{@docRoot}about/versions/jelly-bean.html#android-41">Platform Highlights</a></td></tr> <tr><td><a href="{@docRoot}about/versions/android-4.0.3.html">Android 4.0.3, 4.0.4</a></td> diff --git a/docs/html/guide/topics/renderscript/advanced.jd b/docs/html/guide/topics/renderscript/advanced.jd index 58f5e1f..6a72b97 100644 --- a/docs/html/guide/topics/renderscript/advanced.jd +++ b/docs/html/guide/topics/renderscript/advanced.jd @@ -1,4 +1,4 @@ -page.title=Advanced Renderscript +page.title=Advanced RenderScript parent.title=Computation parent.link=index.html @@ -9,7 +9,7 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#native">Renderscript Runtime Layer</a></li> + <li><a href="#native">RenderScript Runtime Layer</a></li> <li><a href="#reflected">Reflected Layer</a> <ol> <li><a href="#func">Functions</a></li> @@ -25,7 +25,7 @@ parent.link=index.html <li> <a href="#memory">Working with Memory</a> <ol> - <li><a href="#allocating-mem">Allocating and binding memory to the Renderscript</a></li> + <li><a href="#allocating-mem">Allocating and binding memory to the RenderScript</a></li> <li><a href="#read-write">Reading and writing to memory</a></li> @@ -37,36 +37,36 @@ parent.link=index.html <p></p> - <p>Because applications that utilize Renderscript still run inside of the Android VM, + <p>Because applications that utilize RenderScript still run inside of the Android VM, you have access to all of the framework APIs that you are familiar with, but can - utilize Renderscript when appropriate. To facilitate this interaction between - the framework and the Renderscript runtime, an intermediate layer of code is also + utilize RenderScript when appropriate. To facilitate this interaction between + the framework and the RenderScript runtime, an intermediate layer of code is also present to facilitate communication and memory management between the two levels of code. This document goes into more detail about these different layers of code as well as how memory is shared between the Android VM and - Renderscript runtime.</p> + RenderScript runtime.</p> - <h2 id="native">Renderscript Runtime Layer</h2> + <h2 id="native">RenderScript Runtime Layer</h2> - <p>Your Renderscript code is compiled and - executed in a compact and well-defined runtime layer. The Renderscript runtime APIs offer support for + <p>Your RenderScript code is compiled and + executed in a compact and well-defined runtime layer. The RenderScript runtime APIs offer support for intensive computation that is portable and automatically scalable to the amount of cores available on a processor. </p> <p class="note"><strong>Note:</strong> The standard C functions in the NDK must be - guaranteed to run on a CPU, so Renderscript cannot access these libraries, - because Renderscript is designed to run on different types of processors.</p> + guaranteed to run on a CPU, so RenderScript cannot access these libraries, + because RenderScript is designed to run on different types of processors.</p> -<p>You define your Renderscript code in <code>.rs</code> +<p>You define your RenderScript code in <code>.rs</code> and <code>.rsh</code> files in the <code>src/</code> directory of your Android project. The code is compiled to intermediate bytecode by the <code>llvm</code> compiler that runs as part of an Android build. When your application runs on a device, the bytecode is then compiled (just-in-time) to machine code by another <code>llvm</code> compiler that resides on the device. The machine code is optimized for the - device and also cached, so subsequent uses of the Renderscript enabled application does not + device and also cached, so subsequent uses of the RenderScript enabled application does not recompile the bytecode.</p> - <p>Some key features of the Renderscript runtime libraries include:</p> + <p>Some key features of the RenderScript runtime libraries include:</p> <ul> @@ -79,20 +79,20 @@ amount of cores available on a processor. <li>Conversion routines for primitive data types and vectors, matrix routines, and date and time routines</li> - <li>Data types and structures to support the Renderscript system such as Vector types for + <li>Data types and structures to support the RenderScript system such as Vector types for defining two-, three-, or four-vectors.</li> <li>Logging functions</li> </ul> - <p>See the Renderscript runtime API reference for more information on the available functions. + <p>See the RenderScript runtime API reference for more information on the available functions. <h2 id="reflected">Reflected Layer</h2> <p>The reflected layer is a set of classes that the Android build tools generate to allow access - to the Renderscript runtime from the Android framework. This layer also provides methods + to the RenderScript runtime from the Android framework. This layer also provides methods and constructors that allow you to allocate and work with memory for pointers that are defined in -your Renderscript code. The following list describes the major +your RenderScript code. The following list describes the major components that are reflected:</p> <ul> @@ -105,9 +105,9 @@ following items reflected from the <code>.rs</code> file: <ul> <li>Non-static functions</li> - <li>Non-static, global Renderscript variables. Accessor methods are generated for each - variable, so you can read and write the Renderscript variables from the Android - framework. If a global variable is initialized at the Renderscript runtime layer, those + <li>Non-static, global RenderScript variables. Accessor methods are generated for each + variable, so you can read and write the RenderScript variables from the Android + framework. If a global variable is initialized at the RenderScript runtime layer, those values are used to initialize the corresponding values in the Android framework layer. If global variables are marked as <code>const</code>, then a <code>set</code> method is not generated.</p></li> @@ -128,7 +128,7 @@ generated.</p></li> <h3 id="func">Functions</h3> <p>Functions are reflected into the script class itself, located in <code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. For -example, if you declare the following function in your Renderscript code:</p> +example, if you declare the following function in your RenderScript code:</p> <pre> void touch(float x, float y, float pressure, int id) { @@ -155,14 +155,14 @@ public void invoke_touch(float x, float y, float pressure, int id) { } </pre> <p> -Functions cannot have a return value, because the Renderscript system is designed to be -asynchronous. When your Android framework code calls into Renderscript, the call is queued and is -executed when possible. This restriction allows the Renderscript system to function without constant +Functions cannot have a return value, because the RenderScript system is designed to be +asynchronous. When your Android framework code calls into RenderScript, the call is queued and is +executed when possible. This restriction allows the RenderScript system to function without constant interruption and increases efficiency. If functions were allowed to have return values, the call would block until the value was returned.</p> <p> -If you want the Renderscript code to send a value back to the Android framework, use the +If you want the RenderScript code to send a value back to the Android framework, use the <a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function. </p> @@ -172,7 +172,7 @@ function. <p>Variables of supported types are reflected into the script class itself, located in <code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. A set of accessor methods are generated for each variable. For example, if you declare the following variable in -your Renderscript code:</p> +your RenderScript code:</p> <pre>uint32_t unsignedInteger = 1;</pre> <p>then the following code is generated:</p> @@ -329,7 +329,7 @@ public class ScriptField_Point extends android.renderscript.Script.FieldBase { </pre> <p>The generated code is provided to you as a convenience to allocate memory for structs requested -by the Renderscript runtime and to interact with <code>struct</code>s +by the RenderScript runtime and to interact with <code>struct</code>s in memory. Each <code>struct</code>'s class defines the following methods and constructors:</p> <ul> @@ -356,11 +356,11 @@ in memory. Each <code>struct</code>'s class defines the following methods and co </ul> <p>You can specify multiple memory spaces by using the bitwise <code>OR</code> operator. Doing so - notifies the Renderscript runtime that you intend on accessing the data in the + notifies the RenderScript runtime that you intend on accessing the data in the specified memory spaces. The following example allocates memory for a custom data type in both the script and vertex memory spaces:</p> <pre> - ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2, + ScriptField_Point touchPoints = new ScriptField_Point(myRenderScript, 2, Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX); </pre> </li> @@ -370,13 +370,13 @@ in memory. Each <code>struct</code>'s class defines the following methods and co with the <code>struct</code> in your Android code. When you are done manipulating the object, you can push the object to the allocated memory by calling <code>set(Item i, int index, boolean copyNow)</code> and setting the <code>Item</code> to the desired position in -the array. The Renderscript runtime automatically has access to the newly written memory. +the array. The RenderScript runtime automatically has access to the newly written memory. <li>Accessor methods to get and set the values of each field in a struct. Each of these accessor methods have an <code>index</code> parameter to specify the <code>struct</code> in the array that you want to read or write to. Each setter method also has a <code>copyNow</code> parameter that specifies whether or not to immediately sync this memory -to the Renderscript runtime. To sync any memory that has not been synced, call +to the RenderScript runtime. To sync any memory that has not been synced, call <code>copyAll()</code>.</li> <li>The <code>createElement()</code> method creates a description of the struct in memory. This @@ -387,7 +387,7 @@ expand previously allocated memory, maintaining the current values that were pre created.</li> <li><code>copyAll()</code> synchronizes memory that was set on the framework level to the -Renderscript runtime. When you call a set accessor method on a member, there is an optional +RenderScript runtime. When you call a set accessor method on a member, there is an optional <code>copyNow</code> boolean parameter that you can specify. Specifying <code>true</code> synchronizes the memory when you call the method. If you specify false, you can call <code>copyAll()</code> once, and it synchronizes memory for all the @@ -397,7 +397,7 @@ properties that are not yet synchronized.</li> <h3 id="pointer">Pointers</h3> <p>Pointers are reflected into the script class itself, located in <code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. You -can declare pointers to a <code>struct</code> or any of the supported Renderscript types, but a +can declare pointers to a <code>struct</code> or any of the supported RenderScript types, but a <code>struct</code> cannot contain pointers or nested arrays. For example, if you declare the following pointers to a <code>struct</code> and <code>int32_t</code></p> @@ -438,7 +438,7 @@ public Allocation get_intPointer() { <p>A <code>get</code> method and a special method named <code>bind_<em>pointer_name</em></code> (instead of a <code>set()</code> method) is generated. This method allows you to bind the memory -that is allocated in the Android VM to the Renderscript runtime (you cannot allocate +that is allocated in the Android VM to the RenderScript runtime (you cannot allocate memory in your <code>.rs</code> file). For more information, see <a href="#memory">Working with Allocated Memory</a>. </p> @@ -446,14 +446,14 @@ with Allocated Memory</a>. <h2 id="mem-allocation">Memory Allocation APIs</h2> - <p>Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and + <p>Applications that use RenderScript still run in the Android VM. The actual RenderScript code, however, runs natively and needs access to the memory allocated in the Android VM. To accomplish this, you must - attach the memory that is allocated in the VM to the Renderscript runtime. This -process, called binding, allows the Renderscript runtime to seamlessly work with memory that it + attach the memory that is allocated in the VM to the RenderScript runtime. This +process, called binding, allows the RenderScript runtime to seamlessly work with memory that it requests but cannot explicitly allocate. The end result is essentially the same as if you had called <code>malloc</code> in C. The added benefit is that the Android VM can carry out garbage collection as well as -share memory with the Renderscript runtime layer. Binding is only necessary for dynamically allocated memory. Statically -allocated memory is automatically created for your Renderscript code at compile time. See <a href="#figure1">Figure 1</a> +share memory with the RenderScript runtime layer. Binding is only necessary for dynamically allocated memory. Statically +allocated memory is automatically created for your RenderScript code at compile time. See <a href="#figure1">Figure 1</a> for more information on how memory allocation occurs. </p> @@ -479,11 +479,11 @@ understand how these classes work, it is useful to think of them in relation to <p>In most situations, you do not need to call these memory allocation APIs directly. The reflected layer classes generate code to use these APIs automatically and all you need to do to allocate memory is call a constructor that is declared in one of the reflected layer classes and then bind - the resulting memory {@link android.renderscript.Allocation} to the Renderscript. + the resulting memory {@link android.renderscript.Allocation} to the RenderScript. There are some situations where you would want to use these classes directly to allocate memory on your own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to primitive types. You can see how to do this in the - <a href="#allocating-mem">Allocating and binding memory to the Renderscript</a> section. + <a href="#allocating-mem">Allocating and binding memory to the RenderScript</a> section. The following table describes the three memory management classes in more detail:</p> <table id="mem-mgmt-table"> @@ -500,12 +500,12 @@ understand how these classes work, it is useful to think of them in relation to <p>An element describes one cell of a memory allocation and can have two forms: basic or complex.</p> - <p>A basic element contains a single component of data of any valid Renderscript data type. + <p>A basic element contains a single component of data of any valid RenderScript data type. Examples of basic element data types include a single <code>float</code> value, a <code>float4</code> vector, or a single RGB-565 color.</p> <p>Complex elements contain a list of basic elements and are created from - <code>struct</code>s that you declare in your Renderscript code. For instance an allocation + <code>struct</code>s that you declare in your RenderScript code. For instance an allocation can contain multiple <code>struct</code>s arranged in order in memory. Each struct is considered as its own element, rather than each data type within that struct.</p> </td> @@ -552,64 +552,64 @@ understand how these classes work, it is useful to think of them in relation to <h2 id="memory">Working with Memory</h2> -<p>Non-static, global variables that you declare in your Renderscript are allocated memory at compile time. -You can work with these variables directly in your Renderscript code without having to allocate +<p>Non-static, global variables that you declare in your RenderScript are allocated memory at compile time. +You can work with these variables directly in your RenderScript code without having to allocate memory for them at the Android framework level. The Android framework layer also has access to these variables with the provided accessor methods that are generated in the reflected layer classes. If these variables are -initialized at the Renderscript runtime layer, those values are used to initialize the corresponding +initialized at the RenderScript runtime layer, those values are used to initialize the corresponding values in the Android framework layer. If global variables are marked as const, then a <code>set</code> method is not generated.</p> -<p class="note"><strong>Note:</strong> If you are using certain Renderscript structures that contain pointers, such as +<p class="note"><strong>Note:</strong> If you are using certain RenderScript structures that contain pointers, such as <code>rs_program_fragment</code> and <code>rs_allocation</code>, you have to obtain an object of the corresponding Android framework class first and then call the <code>set</code> method for that -structure to bind the memory to the Renderscript runtime. You cannot directly manipulate these structures -at the Renderscript runtime layer. This restriction is not applicable to user-defined structures +structure to bind the memory to the RenderScript runtime. You cannot directly manipulate these structures +at the RenderScript runtime layer. This restriction is not applicable to user-defined structures that contain pointers, because they cannot be exported to a reflected layer class in the first place. A compiler error is generated if you try to declare a non-static, global struct that contains a pointer. </p> -<p>Renderscript also has support for pointers, but you must explicitly allocate the memory in your +<p>RenderScript also has support for pointers, but you must explicitly allocate the memory in your Android framework code. When you declare a global pointer in your <code>.rs</code> file, you allocate memory through the appropriate reflected layer class and bind that memory to the native -Renderscript layer. You can interact with this memory from the Android framework layer as well as -the Renderscript layer, which offers you the flexibility to modify variables in the most +RenderScript layer. You can interact with this memory from the Android framework layer as well as +the RenderScript layer, which offers you the flexibility to modify variables in the most appropriate layer.</p> - <h3 id="allocating-mem">Allocating and binding dynamic memory to the Renderscript</h3> + <h3 id="allocating-mem">Allocating and binding dynamic memory to the RenderScript</h3> <p>To allocate dynamic memory, you need to call the constructor of a {@link android.renderscript.Script.FieldBase} class, which is the most common way. An alternative is to create an {@link android.renderscript.Allocation} manually, which is required for things such as primitive type pointers. You should use a {@link android.renderscript.Script.FieldBase} class constructor whenever available for simplicity. After obtaining a memory allocation, call the reflected <code>bind</code> method of the pointer to bind the allocated memory to the - Renderscript runtime.</p> + RenderScript runtime.</p> <p>The example below allocates memory for both a primitive type pointer, <code>intPointer</code>, and a pointer to a struct, <code>touchPoints</code>. It also binds the memory to the - Renderscript:</p> + RenderScript:</p> <pre> -private RenderScript myRenderscript; +private RenderScript myRenderScript; private ScriptC_example script; private Resources resources; public void init(RenderScript rs, Resources res) { - myRenderscript = rs; + myRenderScript = rs; resources = res; //allocate memory for the struct pointer, calling the constructor - ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2); + ScriptField_Point touchPoints = new ScriptField_Point(myRenderScript, 2); //Create an element manually and allocate memory for the int pointer - intPointer = Allocation.createSized(myRenderscript, Element.I32(myRenderscript), 2); + intPointer = Allocation.createSized(myRenderScript, Element.I32(myRenderScript), 2); - //create an instance of the Renderscript, pointing it to the bytecode resource - mScript = new ScriptC_example(myRenderscript, resources, R.raw.example); + //create an instance of the RenderScript, pointing it to the bytecode resource + mScript = new ScriptC_example(myRenderScript, resources, R.raw.example); - //bind the struct and int pointers to the Renderscript + //bind the struct and int pointers to the RenderScript mScript.bind_touchPoints(touchPoints); script.bind_intPointer(intPointer); @@ -618,29 +618,29 @@ public void init(RenderScript rs, Resources res) { </pre> <h3>Reading and writing to memory</h3> - <p>You can read and write to statically and dynamically allocated memory both at the Renderscript runtime + <p>You can read and write to statically and dynamically allocated memory both at the RenderScript runtime and Android framework layer.</p> <p>Statically allocated memory comes with a one-way communication restriction -at the Renderscript runtime level. When Renderscript code changes the value of a variable, it is not +at the RenderScript runtime level. When RenderScript code changes the value of a variable, it is not communicated back to the Android framework layer for efficiency purposes. The last value that is set from the Android framework is always returned during a call to a <code>get</code> method. However, when Android framework code modifies a variable, that change can be communicated to -the Renderscript runtime automatically or synchronized at a later time. If you need to send data -from the Renderscript runtime to the Android framework layer, you can use the +the RenderScript runtime automatically or synchronized at a later time. If you need to send data +from the RenderScript runtime to the Android framework layer, you can use the <a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function to overcome this limitation. </p> -<p>When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated +<p>When working with dynamically allocated memory, any changes at the RenderScript runtime layer are propagated back to the Android framework layer if you modified the memory allocation using its associated pointer. -Modifying an object at the Android framework layer immediately propagates that change back to the Renderscript +Modifying an object at the Android framework layer immediately propagates that change back to the RenderScript runtime layer.</p> <h4>Reading and writing to global variables</h4> <p>Reading and writing to global variables is a straightforward process. You can use the accessor methods - at the Android framework level or set them directly in the Renderscript code. Keep in mind that any - changes that you make in your Renderscript code are not propagated back to the Android framework layer.</p> + at the Android framework level or set them directly in the RenderScript code. Keep in mind that any + changes that you make in your RenderScript code are not propagated back to the Android framework layer.</p> <p>For example, given the following struct declared in a file named <code>rsfile.rs</code>:</p> <pre> @@ -659,8 +659,8 @@ point.x = 1; point.y = 1; </pre> -<p>You can assign values to the struct at the Android framework layer like this. These values are -propagated back to the Renderscript runtime level:</p> +<p>You can assign values to the struct at the Android framework layer like this. These values are +propagated back to the RenderScript runtime level:</p> <pre> ScriptC_rsfile mScript; @@ -672,7 +672,7 @@ i.y = 1; mScript.set_point(i); </pre> -<p>You can read the values in your Renderscript code like this:</p> +<p>You can read the values in your RenderScript code like this:</p> <pre> rsDebug("Printing out a Point", point.x, point.y); @@ -680,7 +680,7 @@ rsDebug("Printing out a Point", point.x, point.y); <p>You can read the values in the Android framework layer with the following code. Keep in mind that this code only returns a value if one was set at the Android framework level. You will get a null pointer -exception if you only set the value at the Renderscript runtime level:</p> +exception if you only set the value at the RenderScript runtime level:</p> <pre> Log.i("TAGNAME", "Printing out a Point: " + mScript.get_point().x + " " + mScript.get_point().y); @@ -689,9 +689,9 @@ System.out.println(point.get_x() + " " + point.get_y()); <h4>Reading and writing global pointers</h4> -<p>Assuming that memory has been allocated in the Android framework level and bound to the Renderscript runtime, +<p>Assuming that memory has been allocated in the Android framework level and bound to the RenderScript runtime, you can read and write memory from the Android framework level by using the <code>get</code> and <code>set</code> methods for that pointer. -In the Renderscript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated +In the RenderScript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated back to the Android framework layer, unlike with statically allocated memory.</p> <p>For example, given the following pointer to a <code>struct</code> in a file named <code>rsfile.rs</code>:</p> @@ -726,5 +726,5 @@ ScriptField_Point p = new ScriptField_Point(mRS, 1); points.get_x(0); </pre> -<p>Once memory is already bound, you do not have to rebind the memory to the Renderscript +<p>Once memory is already bound, you do not have to rebind the memory to the RenderScript runtime every time you make a change to a value.</p> diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd index 5f466ce..607d16e 100644 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/renderscript/compute.jd @@ -1,4 +1,4 @@ -page.title=Renderscript Computation +page.title=RenderScript parent.title=Computation parent.link=index.html @@ -9,15 +9,8 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#overview">Renderscript System Overview</a></li> - <li><a href="#filterscript">Filterscript</a></li> - <li> - <a href="#creating-renderscript">Creating a Computation Renderscript</a> - <ol> - <li><a href="#creating-rs-file">Creating the Renderscript file</a></li> - <li><a href="#calling">Calling the Renderscript code</a></li> - </ol> - </li> + <li><a href="#writing-an-rs-kernel">Writing a RenderScript Kernel</a></li> + <li><a href="#using-rs-from-java">Using RenderScript from Java Code</a></li> </ol> <h2>Related Samples</h2> @@ -29,371 +22,204 @@ parent.link=index.html </div> </div> - <p>Renderscript offers a high performance computation API at the native -level that you write in C (C99 standard). Renderscript gives your apps the ability to run -operations with automatic parallelization across all available processor cores. -It also supports different types of processors such as the CPU, GPU or DSP. Renderscript -is useful for apps that do image processing, mathematical modeling, or any operations -that require lots of mathematical computation.</p> - -<p>In addition, you have access to all of these features without having to write code to -support different architectures or a different amount of processing cores. You also -do not need to recompile your application for different processor types, because Renderscript -code is compiled on the device at runtime.</p> - -<p class="note"><strong>Deprecation Notice</strong>: Earlier versions of Renderscript included - an experimental graphics engine component. This component -is now deprecated as of Android 4.1 (most of the APIs in <code>rs_graphics.rsh</code> -and the corresponding APIs in {@link android.renderscript}). -If you have apps that render graphics with Renderscript, we highly -recommend you convert your code to another Android graphics rendering option.</p> - - <h2 id="overview">Renderscript System Overview</h2> - <p>The Renderscript runtime operates at the native level and still needs to communicate -with the Android VM, so the way a Renderscript application is set up is different from a pure VM -application. An application that uses Renderscript is still a traditional Android application that -runs in the VM, but you write Renderscript code for the parts of your program that require -it. No matter what you use it for, Renderscript remains platform -independent, so you do not have to target multiple architectures (for example, -ARM v5, ARM v7, x86).</p> - -<p>The Renderscript system adopts a control and slave architecture where the low-level Renderscript runtime -code is controlled by the higher level Android system that runs in a virtual machine (VM). The -Android VM still retains all control of memory management and binds memory that it allocates to -the Renderscript runtime, so the Renderscript code can access it. The Android framework makes -asynchronous calls to Renderscript, and the calls are placed in a message queue and processed -as soon as possible. Figure 1 shows how the Renderscript system is structured.</p> - - <img id="figure1" src="{@docRoot}images/rs_overview.png" /> - <p class="img-caption"><strong>Figure 1.</strong> Renderscript system overview</p> - - <p>When using Renderscript, there are three layers of APIs that enable communication between the - Renderscript runtime and Android framework code:</p> - - <ul> - <li>The Renderscript runtime APIs allow you to do the computation - that is required by your application.</li> - - <li>The reflected layer APIs are a set of classes that are reflected from your Renderscript -runtime code. It is basically a wrapper around the Renderscript code that allows the Android -framework to interact with the Renderscript runtime. The Android build tools automatically generate the -classes for this layer during the build process. These classes eliminate the need to write JNI glue -code, like with the NDK.</li> - - <li>The Android framework layer calls the reflected layer to access the Renderscript - runtime.</li> - </ul> - -<p>Because of the way Renderscript is structured, the main advantages are:</p> - <ul> - <li>Portability: Renderscript is designed to run on many types of devices with different - processor (CPU, GPU, and DSP for instance) architectures. It supports all of these architectures without - having to target each device, because the code is compiled and cached on the device - at runtime.</li> - - <li>Performance: Renderscript provides a high performance computation API with seamless parallelization - across the amount of cores on the device.</li> - - <li>Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code.</li> - </ul> - - <p>The main disadvantages are:</p> - - <ul> - <li>Development complexity: Renderscript introduces a new set of APIs that you have to learn.</li> - - <li>Debugging visibility: Renderscript can potentially execute (planned feature for later releases) - on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult. - </li> - </ul> - -<p>For a more detailed explanation of how all of these layers work together, see - <a href="{@docRoot}guide/topics/renderscript/advanced.html">Advanced Renderscript</a>.<p> - -<h2 id="filterscript">Filterscript</h2> - -<p>Introduced in Android 4.2 (API Level 17), Filterscript defines a subset of Renderscript -that focuses on image processing operations, such as those -that you would typically write with an OpenGL ES fragment shader. You still write your scripts -using the standard Renderscript runtime APIs, but within stricter -constraints that ensure wider compatibility and improved optimization across -CPUs, GPUs, and DSPs. At compile time, the precompiler evaluates Filterscript files and -applies a more stringent set of warnings and errors than -it does for standard Renderscript files. The following list describes the major constraints -of Filterscript when compared to Renderscript:</p> +<p>RenderScript is a framework for running computationally intensive tasks at high performance on +Android. RenderScript is primarily oriented for use with data-parallel computation, although serial +computationally intensive workloads can benefit as well. The RenderScript runtime will parallelize +work across all processors available on a device, such as multi-core CPUs, GPUs, or DSPs, allowing +you to focus on expressing algorithms rather than scheduling work or load balancing. RenderScript is +especially useful for applications performing image processing, computational photography, or +computer vision.</p> +<p>To begin with RenderScript, there are two main concepts you should understand:</p> <ul> -<li>Inputs and return values of root functions cannot contain pointers. The default root function -signature contains pointers, so you must use the <code>__attribute__((kernel))</code> attribute to declare a custom -root function when using Filterscript.</li> -<li>Built-in types cannot exceed 32-bits.</li> -<li>Filterscript must always use relaxed floating point precision by using the -<code>rs_fp_relaxed</code> pragma.</li> -<li>Filterscript files must end with an <code>.fs</code> extension, instead of an <code>.rs</code> extension.</li> -</ul> -<h2 id="creating-renderscript">Creating a Renderscript</h2> +<li>High-performance compute kernels are written in a C99-derived language.</li> -<p>Renderscript scales to the amount of -processing cores available on the device. This is enabled through a function named -<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level). -that automatically partitions work across available processing cores on the device.</p> +<li>A Java API is used for managing the lifetime of RenderScript resources and controlling kernel +execution.</li> +</ul> -<p>Implementing a Renderscript involves creating a <code>.rs</code> file that contains -your Renderscript code and calling it at the Android framework level with the -<code>forEach_root()</code> or at the Renderscript runtime level with the -<code>rsForEach()</code> function. The following diagram describes how a typical -Renderscript is set up:</p><img src="{@docRoot}images/rs_compute.png"> +<h2 id="writing-an-rs-kernel">Writing a RenderScript Kernel</h2> -<p class="img-caption"><strong>Figure 1.</strong> Renderscript overview</p> +<p>A RenderScript kernel typically resides in a <code>.rs</code> file in the +<code><project_root>/src/</code> directory; each <code>.rs</code> file is called a +script. Every script contains its own set of kernels, functions, and variables. A script can +contain:</p> -<p>The following sections describe how to create a simple Renderscript and use it in an -Android application. This example uses the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript -sample</a> that is provided in the SDK as a guide (some code has been modified from its original -form for simplicity).</p> +<ul> +<li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of the +RenderScript kernel language used in this script. Currently, 1 is the only valid value.</li> + +<li>A pragma declaration (<code>#pragma rs java_package_name(com.example.app)</code>) that +declares the package name of the Java classes reflected from this script.</li> + +<li>Some number of invokable functions. An invokable function is a single-threaded RenderScript +function that you can call from your Java code with arbitrary arguments. These are often useful for +initial setup or serial computations within a larger processing pipeline.</li> + +<li>Some number of script globals. A script global is equivalent to a global variable in C. You can +access script globals from Java code, and these are often used for parameter passing to RenderScript +kernels.</li> + +<li>Some number of compute kernels. A kernel is a parallel function that executes across every +{@link android.renderscript.Element} within an {@link android.renderscript.Allocation}. + +<p>A simple kernel may look like the following:</p> + +<pre>uchar4 __attribute__((kernel)) invert(uchar4 in, uint32_t x, uint32_t y) { + uchar4 out = in; + out.r = 255 - in.r; + out.g = 255 - in.g; + out.b = 255 - in.b; + return out; +}</pre> + +<p>In most respects, this is identical to a standard C function. The first notable feature is the +<code>__attribute__((kernel))</code> applied to the function prototype. This denotes that the +function is a RenderScript kernel instead of an invokable function. The next feature is the +<code>in</code> argument and its type. In a RenderScript kernel, this is a special argument that is +automatically filled in based on the input {@link android.renderscript.Allocation} passed to the +kernel launch. By default, the kernel is run across an entire {@link +android.renderscript.Allocation}, with one execution of the kernel body per {@link +android.renderscript.Element} in the {@link android.renderscript.Allocation}. The third notable +feature is the return type of the kernel. The value returned from the kernel is automatically +written to the appropriate location in the output {@link android.renderscript.Allocation}. The +RenderScript runtime checks to ensure that the {@link android.renderscript.Element} types of the +input and output Allocations match the kernel's prototype; if they do not match, an exception is +thrown.</p> + +<p>A kernel may have an input {@link android.renderscript.Allocation}, an output {@link +android.renderscript.Allocation}, or both. A kernel may not have more than one input or one output +{@link android.renderscript.Allocation}. If more than one input or output is required, those objects +should be bound to <code>rs_allocation</code> script globals and accessed from a kernel or invokable +function via <code>rsGetElementAt_<em>type</em>()</code> or +<code>rsSetElementAt_<em>type</em>()</code>.</p> + +<p>A kernel may access the coordinates of the current execution using the <code>x</code>, +<code>y</code>, and <code>z</code> arguments. These arguments are optional, but the type of the +coordinate arguments must be <code>uint32_t</code>.</p></li> + +<li>An optional <code>init()</code> function. An <code>init()</code> function is a special type of +invokable function that is run when the script is first instantiated. This allows for some +computation to occur automatically at script creation.</li> + +<li>Some number of static script globals and functions. A static script global is equivalent to a +script global except that it cannot be set from Java code. A static function is a standard C +function that can be called from any kernel or invokable function in the script but is not exposed +to the Java API. If a script global or function does not need to be called from Java code, it is +highly recommended that those be declared <code>static</code>.</li> </ul> -<h3 id="creating-rs-file">Creating the Renderscript file</h3> +<h4>Setting floating point precision</h4> -<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the -<code><project_root>/src/</code> directory. This code contains the computation logic -and declares all necessary variables and pointers. -Every <code>.rs</code> file generally contains the following items:</p> +<p>You can control the required level of floating point precision in a script. This is useful if +full IEEE 754-2008 standard (used by default) is not required. The following pragmas can set a +different level of floating point precision:</p> <ul> - <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) - that declares the package name of the <code>.java</code> reflection of this Renderscript.</li> - - <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of - Renderscript that you are using (1 is the only value for now).</li> - - <li><p>A root function (or kernel) that is the main entry point to your Renderscript. - The default <code>root()</code> function must return - <code>void</code> and accept the following arguments:</p> - - <ul> - <li>Pointers to memory allocations that are used for the input and output of the - Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform - versions or older. Android 4.0 (API level 14) and later requires one or both of these - allocations.</li> - </ul> - - <p>The following arguments are optional, but both must be supplied if you choose to use - them:</p> - - <ul> - <li>A pointer for user-defined data that the Renderscript might need to carry out - computations in addition to the necessary allocations. This can be a pointer to a simple - primitive or a more complex struct.</li> - - <li>The size of the user-defined data.</li> - </ul> - - <p>Starting in Android 4.1 (API Level 16), you can choose to define your own root function arguments - without adhering to the default root function signature described previously. In addition, - you can declare multiple root functions in the same Renderscript. To do this, use the <code>__attribute__((kernel))</code> - attribute to define a custom root function. For example, here's a root function - that returns a <code>uchar4</code> and accepts two <code>uint32_t</code> types: </p> - - <pre> - uchar4 __attribute__((kernel)) root(uint32_t x, uint32_t y) { - ... - } - </pre> - </li> - - <li>An optional <code>init()</code> function. This allows you to do any initialization - before the root function runs, such as initializing variables. This - function runs once and is called automatically when the Renderscript starts, before anything - else in your Renderscript.</li> - - <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can - be declared in <code>.rsh</code> files if desired)</li> -</ul> -<p>The following code shows how the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html"> -mono.rs</a> file is implemented:</p> -<pre> -#pragma version(1) -#pragma rs java_package_name(com.example.android.rs.hellocompute) - -//multipliers to convert a RGB colors to black and white -const static float3 gMonoMult = {0.299f, 0.587f, 0.114f}; - -void root(const uchar4 *v_in, uchar4 *v_out) { - //unpack a color to a float4 - float4 f4 = rsUnpackColor8888(*v_in); - //take the dot product of the color and the multiplier - float3 mono = dot(f4.rgb, gMonoMult); - //repack the float to a color - *v_out = rsPackColorTo8888(mono); -} -</pre> +<li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that require + floating point precision as outlined by the IEEE 754-2008 standard. -<h4>Setting floating point precision</h4> -<p>You can define the floating point precision required by your compute algorithms. This is useful if you - require less precision than the IEEE 754-2008 standard (used by default). You can define -the floating-point precision level of your script with the following pragmas:</p> - -<ul> - <li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that - require floating point precision as outlined by the IEEE 754-2008 standard. </li> - <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require - strict IEEE 754-2008 compliance and can tolerate less precision. This mode enables - flush-to-zero for denorms and round-towards-zero. + + <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require strict IEEE 754-2008 + compliance and can tolerate less precision. This mode enables flush-to-zero for denorms and + round-towards-zero. + </li> - <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision requirements. This mode enables - everything in <code>rs_fp_relaxed</code> along with the following: + + <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision + requirements. This mode enables everything in <code>rs_fp_relaxed</code> along with the + following: + <ul> + <li>Operations resulting in -0.0 can return +0.0 instead.</li> <li>Operations on INF and NAN are undefined.</li> </ul> </li> </ul> -<h4>Script intrinsics</h4> -<p>Renderscript adds support for a set of script intrinsics, which are pre-implemented -filtering primitives that reduce the amount of -code that you need to write. They also are implemented to ensure that your app gets the -maximum performance gain possible.</p> +<p>Most applications can use <code>rs_fp_relaxed</code> without any side effects. This may be very +beneficial on some architectures due to additional optimizations only available with relaxed +precision (such as SIMD CPU instructions).</p> -<p> -Intrinsics are available for the following: -<ul> - <li>{@link android.renderscript.ScriptIntrinsicBlend Blends}</li> - <li>{@link android.renderscript.ScriptIntrinsicBlur Blur}</li> - <li>{@link android.renderscript.ScriptIntrinsicColorMatrix Color matrix}</li> - <li>{@link android.renderscript.ScriptIntrinsicConvolve3x3 3x3 convolve}</li> - <li>{@link android.renderscript.ScriptIntrinsicConvolve5x5 5x5 convolve}</li> - <li>{@link android.renderscript.ScriptIntrinsicLUT Per-channel lookup table}</li> - <li>{@link android.renderscript.ScriptIntrinsicYuvToRGB Converting an Android YUV buffer to RGB}</li> -</ul> +<h2 id="using-rs-from-java">Using RenderScript from Java Code</h2> -<h3 id="calling">Calling the Renderscript code</h3> +<p>Using RenderScript from Java code relies on the {@link android.renderscript} APIs. Most +applications follow the same basic usage patterns:</p> -<p>You can call the Renderscript from your Android framework code by -creating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>) -class. This class contains a method, <code>forEach_root()</code>, that lets you invoke -<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it -at the Renderscript runtime level. This technique allows your Android application to offload -intensive mathematical calculations to Renderscript. See the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see -how a simple Android application can utilize Renderscript.</p> +<ol> -<p>To call Renderscript at the Android framework level:</p> +<li><strong>Initialize a RenderScript context.</strong> The {@link +android.renderscript.RenderScript} context, created with {@link +android.renderscript.RenderScript#create}, ensures that RenderScript can be used and provides an +object to control the lifetime of all subsequent RenderScript objects. You should consider context +creation to be a potentially long-running operation, since it may create resources on different +pieces of hardware; it should not be in an application's critical path if at all +possible. Typically, an application will have only a single RenderScript context at a time.</li> + +<li><strong>Create at least one {@link android.renderscript.Allocation} to be passed to a +script.</strong> An {@link android.renderscript.Allocation} is a RenderScript object that provides +storage for a fixed amount of data. Kernels in scripts take {@link android.renderscript.Allocation} +objects as their input and output, and {@link android.renderscript.Allocation} objects can be +accessed in kernels using <code>rsGetElementAt_<em>type</em>()</code> and +<code>rsSetElementAt_<em>type</em>()</code> when bound as script globals. {@link +android.renderscript.Allocation} objects allow arrays to be passed from Java code to RenderScript +code and vice-versa. {@link android.renderscript.Allocation} objects are typically created using +{@link android.renderscript.Allocation#createTyped} or {@link +android.renderscript.Allocation#createFromBitmap}.</li> + +<li><strong>Create whatever scripts are necessary.</strong> There are two types of scripts available +to you when using RenderScript: -<ol> - <li>Allocate memory that is needed by the Renderscript in your Android framework code. - You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level - 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only - one or both {@link android.renderscript.Allocation}s.</li> - - <li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li> - - <li>Call <code>forEach_root()</code>, passing in the allocations, the - Renderscript, and any optional user-defined data. The output allocation will contain the output - of the Renderscript.</li> -</ol> - -<p>The following example, taken from the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes -a bitmap and outputs a black and white version of it. The -<code>createScript()</code> method carries out the steps described previously. This method calls the -Renderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed -as well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p> -<pre> -package com.example.android.rs.hellocompute; - -import android.app.Activity; -import android.os.Bundle; -import android.graphics.BitmapFactory; -import android.graphics.Bitmap; -import android.renderscript.RenderScript; -import android.renderscript.Allocation; -import android.widget.ImageView; - -public class HelloCompute extends Activity { - private Bitmap mBitmapIn; - private Bitmap mBitmapOut; - - private RenderScript mRS; - private Allocation mInAllocation; - private Allocation mOutAllocation; - private ScriptC_mono mScript; - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.main); - - mBitmapIn = loadBitmap(R.drawable.data); - mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(), - mBitmapIn.getConfig()); - - ImageView in = (ImageView) findViewById(R.id.displayin); - in.setImageBitmap(mBitmapIn); - - ImageView out = (ImageView) findViewById(R.id.displayout); - out.setImageBitmap(mBitmapOut); - - createScript(); - } - private void createScript() { - mRS = RenderScript.create(this); - mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn, - Allocation.MipmapControl.MIPMAP_NONE, - Allocation.USAGE_SCRIPT); - mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType()); - mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono); - mScript.forEach_root(mInAllocation, mOutAllocation); - mOutAllocation.copyTo(mBitmapOut); - } - - private Bitmap loadBitmap(int resource) { - final BitmapFactory.Options options = new BitmapFactory.Options(); - options.inPreferredConfig = Bitmap.Config.ARGB_8888; - return BitmapFactory.decodeResource(getResources(), resource, options); - } -} -</pre> - -<p>To call Renderscript from another Renderscript file:</p> -<ol> - <li>Allocate memory that is needed by the Renderscript in your Android framework code. - You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level - 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only - one or both {@link android.renderscript.Allocation}s.</li> - - <li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data. - The output allocation will contain the output of the Renderscript.</li> -</ol> - -<pre> -rs_script script; -rs_allocation in_allocation; -rs_allocation out_allocation; -UserData_t data; -... -rsForEach(script, in_allocation, out_allocation, &data, sizeof(data)); -</pre> -</p> -<p>In this example, assume that the script and memory allocations have already been -allocated and bound at the Android framework level and that <code>UserData_t</code> is a struct -declared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code> -is optional, but useful if your Renderscript requires additional information other than -the necessary memory allocations.</p> - - -<h4>Script groups</h4> - -<p>You can group Renderscript scripts together and execute them all with a single call as though -they were part of a single script. This allows Renderscript to optimize execution of the scripts -in ways that it could not do if the scripts were executed individually.</p> - -<p>To build a script groupm, use the {@link android.renderscript.ScriptGroup.Builder} class to create a {@link android.renderscript.ScriptGroup} -defining the operations. At execution time, Renderscript optimizes the run order and the connections between these -operations for best performance. - -<p class="note"><strong>Important:</strong> The script group must be a direct acyclic graph for this feature to work.</p> +<ul> + +<li><strong>ScriptC</strong>: These are the user-defined scripts as described in <a +href="#writing-an-rs-kernel">Writing a RenderScript Kernel</a> above. Every script has a Java class +reflected by the RenderScript compiler in order to make it easy to access the script from Java code; +this class will have the name <code>ScriptC_<em>filename</em></code>. For example, if the kernel +above was located in <code>invert.rs</code> and a RenderScript context was already located in +<code>mRS</code>, the Java code to instantiate the script would be: + +<pre>ScriptC_invert invert = new ScriptC_invert(mRenderScript);</pre></li> + +<li><strong>ScriptIntrinsic</strong>: These are built-in RenderScript kernels for common operations, +such as Gaussian blur, convolution, and image blending. For more information, see the subclasses of +{@link android.renderscript.ScriptIntrinsic}.</li> + +</ul></li> + +<li><strong>Populate Allocations with data.</strong> Except for Allocations created with {@link +android.renderscript#createFromBitmap}, an Allocation will be populated with empty data when it is +first created. To populate an Allocation, use one of the <code>copy</code> methods in {@link +android.renderscript.Allocation}.</li> + +<li><strong>Set any necessary script globals.</strong> Globals may be set using methods in the same +<code>ScriptC_<em>filename</em></code> class with methods named +<code>set_<em>globalname</em></code>. For example, in order to set an <code>int</code> named +<code>elements</code>, use the Java method <code>set_elements(int)</code>. RenderScript objects can +also be set in kernels; for example, the <code>rs_allocation</code> variable named +<code>lookup</code> can be set with the method <code>set_lookup(Allocation)</code>.</li> + +<li><strong>Launch the appropriate kernels.</strong> Methods to launch a given kernel will be +reflected in the same <code>ScriptC_<em>filename</em></code> class with methods named +<code>forEach_<em>kernelname</em>()</code>. These launches are asynchronous, and launches will be +serialized in the order in which they are launched. Depending on the arguments to the kernel, the +method will take either one or two Allocations. By default, a kernel will execute over the entire +input or output Allocation; to execute over a subset of that Allocation, pass an appropriate {@link +android.renderscript.Script.LaunchOptions} as the last argument to the <code>forEach</code> method. + +<p>Invoked functions can be launched using the <code>invoke_<em>functionname</em></code> methods +reflected in the same <code>ScriptC_<em>filename</em></code> class.</p></li> + +<li><strong>Copy data out of {@link android.renderscript.Allocation} objects.</strong> In order to +access data from an {@link android.renderscript.Allocation} from Java code, that data must be copied +back to Java buffers using one of the <code>copy</code> methods in {@link +android.renderscript.Allocation}. These functions will synchronize with asynchronous kernel and +function launches as necessary.</li> + +<li><strong>Tear down the RenderScript context.</strong> The RenderScript context can be destroyed +with {@link android.renderscript.RenderScript#destroy} or by allowing the RenderScript context +object to be garbage collected. This will cause any further use of any object belonging to that +context to throw an exception.</li> </ol>
\ No newline at end of file diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/renderscript/index.jd index b5c53ff..d23ba69 100644 --- a/docs/html/guide/topics/renderscript/index.jd +++ b/docs/html/guide/topics/renderscript/index.jd @@ -1,6 +1,6 @@ page.title=Computation page.landing=true -page.landing.intro=Renderscript provides a platform-independent computation engine that operates at the native level. Use it to accelerate your apps that require extensive computational horsepower. +page.landing.intro=RenderScript provides a platform-independent computation engine that operates at the native level. Use it to accelerate your apps that require extensive computational horsepower. page.landing.image= @jd:body @@ -12,16 +12,16 @@ page.landing.image= <a href="http://android-developers.blogspot.com/2013/01/evolution-of-renderscript-performance.html"> - <h4>Evolution of Renderscript Performance</h4> - <p>It’s been a year since the last blog post on Renderscript, and with the release + <h4>Evolution of RenderScript Performance</h4> + <p>It’s been a year since the last blog post on RenderScript, and with the release of Android 4.2, it’s a good time to talk about the performance work that we’ve done since then. One of the major goals of this past year was to improve the performance - of common image-processing operations with Renderscript.</p> </a> + of common image-processing operations with RenderScript.</p> </a> <a href="http://android-developers.blogspot.com/2012/01/levels-in-renderscript.html"> - <h4>Levels in Renderscript</h4> - <p>For ICS, Renderscript (RS) has been updated with several new features to simplify + <h4>Levels in RenderScript</h4> + <p>For ICS, RenderScript (RS) has been updated with several new features to simplify adding compute acceleration to your application. RS is interesting for compute acceleration when you have large buffers of data on which you need to do significant processing. In this example we will look at applying a levels/saturation operation @@ -30,11 +30,11 @@ href="http://android-developers.blogspot.com/2012/01/levels-in-renderscript.html <a href="http://android-developers.blogspot.com/2011/03/renderscript.html"> - <h4>Renderscript Part 2</h4> - <p>In Introducing Renderscript I gave a brief overview of this technology. - In this post I’ll look at "compute" in more detail. In Renderscript we use + <h4>RenderScript Part 2</h4> + <p>In Introducing RenderScript I gave a brief overview of this technology. + In this post I’ll look at "compute" in more detail. In RenderScript we use "compute" to mean offloading of data processing from Dalvik code to - Renderscript code which may run on the same or different processor(s).</p> + RenderScript code which may run on the same or different processor(s).</p> </a> </div> diff --git a/docs/html/guide/topics/resources/drawable-resource.jd b/docs/html/guide/topics/resources/drawable-resource.jd index a34ed6c..dee28fe 100644 --- a/docs/html/guide/topics/resources/drawable-resource.jd +++ b/docs/html/guide/topics/resources/drawable-resource.jd @@ -174,6 +174,7 @@ In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" | "fill_vertical" | "center_horizontal" | "fill_horizontal" | "center" | "fill" | "clip_vertical" | "clip_horizontal"] + android:mipMap=["true" | "false"] android:tileMode=["disabled" | "clamp" | "repeat" | "mirror"] /> </pre> </dd> @@ -245,6 +246,12 @@ the right edge, a right gravity clips the left edge, and neither clips both edge </td></tr> </table> </dd> + + <dt><code>android:mipMap</code></dt> + <dd><em>Boolean</em>. Enables or disables the mipmap hint. See {@link + android.graphics.Bitmap#setHasMipMap setHasMipMap()} for more information. + Default value is false.</dd> + <dt><code>android:tileMode</code></dt> <dd><em>Keyword</em>. Defines the tile mode. When the tile mode is enabled, the bitmap is repeated. Gravity is ignored when the tile mode is enabled. diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index c5bbdbc..453d9d7 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -4,6 +4,14 @@ parent.title=User Interface parent.link=index.html @jd:body + +<a class="notice-designers top" href="{@docRoot}design/patterns/actionbar.html"> + <div> + <h3>Design Guide</h3> + <p>Action Bar</p> + </div> +</a> + <div id="qv-wrapper"> <div id="qv"> @@ -12,23 +20,20 @@ parent.link=index.html <li><a href="#Adding">Adding the Action Bar</a> <ol> <li><a href="#Removing">Removing the action bar</a></li> + <li><a href="#Logo">Using a logo instead of an icon</a></li> </ol> </li> <li><a href="#ActionItems">Adding Action Items</a> <ol> - <li><a href="#ChoosingActionItems">Choosing your action items</a></li> + <li><a href="#ActionEvents">Handling clicks on action items</a></li> <li><a href="#SplitBar">Using split action bar</a></li> </ol> </li> - <li><a href="#Home">Using the App Icon for Navigation</a> - <ol> - <li><a href="#Up">Navigating up</a></li> - </ol> - </li> + <li><a href="#Home">Navigating Up with the App Icon</a></li> <li><a href="#ActionView">Adding an Action View</a> <ol> <li><a href="#ActionViewCollapsing">Handling collapsible action views</a></li> - </ol> + </ol> </li> <li><a href="#ActionProvider">Adding an Action Provider</a> <ol> @@ -44,662 +49,600 @@ parent.link=index.html <li><a href="#ActionItemStyles">Action items</a></li> <li><a href="#NavigationStyles">Navigation tabs</a></li> <li><a href="#DropDownStyles">Drop-down lists</a></li> - <li><a href="#AdvancedStyles">Advanced styling</a></li> + <li><a href="#StyleExample">Example theme</a></li> </ol> </li> </ol> <h2>Key classes</h2> <ol> - <li>{@link android.app.ActionBar}</li> + <li>{@link android.support.v7.app.ActionBar}</li> <li>{@link android.view.Menu}</li> - <li>{@link android.view.ActionProvider}</li> </ol> - <h2>Related samples</h2> - <ol> - <li><a -href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a></li> - <li><a -href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a></li> - <li><a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#ActionBar"> -API Demos</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a -href="{@docRoot}design/patterns/actionbar.html">Android Design: Action Bar</a></li> - <li><a href="{@docRoot}guide/topics/ui/menus.html">Menus</a></li> - <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets -and Handsets</a></li> - </ol> </div> </div> -<p>The action bar is a window feature that identifies the application and user location, and -provides user actions and navigation modes. You should use the action bar in most activities that -need to prominently present user actions or global navigation, because the action bar offers users a -consistent interface across applications and the system gracefully adapts the action bar's -appearance for different screen configurations. You can control the behaviors and visibility of the -action bar with the {@link android.app.ActionBar} APIs, which were added in Android 3.0 (API level -11).</p> +<p>The action bar is a window feature that identifies the user location, and +provides user actions and navigation modes. Using the action bar offers your users a +familiar interface across applications that the system gracefully adapts +for different screen configurations.</p> -<p>The primary goals of the action bar are to:</p> +<img src="{@docRoot}images/ui/actionbar@2x.png" alt="" width="428" height="215" /> +<p class="img-caption"><strong>Figure 1.</strong> An action bar that includes the [1] app icon, +[2] two action items, and [3] action overflow.</p> -<ul> - <li>Provide a dedicated space for identifying the application brand and user location. - <p>This is accomplished with the app icon or logo on the left side and the activity title. -You might choose to remove the activity title, however, if the current view is identified by a -navigation label, such as the currently selected tab.</p></li> - - <li>Provide consistent navigation and view refinement across different applications. - <p>The action bar provides built-in tab navigation for switching between <a -href="{@docRoot}guide/components/fragments.html">fragments</a>. It also offers a drop-down -list you can use as an alternative navigation mode or to refine the current view (such as to sort -a list by different criteria).</p> - </li> +<p>The action bar provides several key functions:</p> - <li>Make key actions for the activity (such as "search", "create", "share", etc.) prominent and -accessible to the user in a predictable way. - <p>You can provide instant access to key user actions by placing items from the <a -href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> directly in the action bar, -as "action items." Action items can also provide an "action view," which provides an embedded -widget for even more immediate action behaviors. Menu items that are not promoted -to an action item are available in the overflow menu, revealed by either the device <em>Menu</em> -button -(when available) or by an "overflow menu" button in the action bar (when the device does not -include a <em>Menu</em> button).</p> -</li> +<ul> + <li>Provides a dedicated space for giving your app an identity and indicating the user's + location in the app.</li> + <li>Makes important actions prominent and accessible in a predictable way + (such as <em>Search</em>).</li> + <li>Supports consistent navigation and view switching within apps (with tabs or drop-down + lists).</li> </ul> -<img src="{@docRoot}images/ui/actionbar.png" alt="" width="440" /> -<p class="img-caption"><strong>Figure 1.</strong> Action bar from the <a -href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app (on a -landscape handset), showing the logo on the left, navigation tabs, and an action item on the -right (plus the overflow menu button).</p> +<p>For more information about the action bar's interaction patterns and design guidelines, +see the <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> +design guide.</p> -<p class="note"><strong>Note:</strong> If you're looking for information about the contextual -action bar for displaying contextual action items, see the <a -href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menu</a> guide.</p> +<p>The {@link android.app.ActionBar} APIs were first added in Android 3.0 (API level 11) but they +are also available in the <a href="{@docRoot}tools/support-library/index.html">Support Library</a> +for compatibility with Android 2.2 (API level 7) and above.</p> + +<p><b>This guide focuses on how to use the +support library's action bar</b>, but if your app supports <em>only</em> Android 3.0 or higher, you +should use the {@link android.app.ActionBar} APIs in the framework. Most of the APIs are +the same—but reside in a different package namespace—with a few exceptions to method +names or signatures that are noted in the sections below.</p> -<div class="note design"> -<p><strong>Action Bar Design</strong></p> - <p>For design guidelines, read Android Design's <a -href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> guide.</p> +<div class="caution"> +<p><strong>Caution:</strong> Be certain you import +the {@code ActionBar} class (and related APIs) from the appropriate package:</p> +<ul> +<li>If supporting API levels <em>lower than</em> 11: <br> +{@code import android.support.v7.app.ActionBar}</li> +<li>If supporting <em>only</em> API level 11 and higher: <br> +{@code import android.app.ActionBar}</li> +</ul> </div> +<p class="note"><strong>Note:</strong> If you're looking for information about the <em>contextual +action bar</em> for displaying contextual action items, see the <a +href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menu</a> guide.</p> -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h2>Remaining backward-compatible</h2> -<p>If you want to provide an action bar in your application <em>and</em> remain compatible with -versions of Android older than 3.0, you need to create the action bar in your -activity's layout (because the {@link android.app.ActionBar} class is not available on older -versions).</p> -<p>To help you, the <a -href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a> sample -app provides an API layer and action bar layout that allows your app to use some of the {@link -android.app.ActionBar} APIs and also support older versions of Android by replacing the traditional -title bar with a custom action bar layout.</p> -</div> -</div> <h2 id="Adding">Adding the Action Bar</h2> -<p>Beginning with Android 3.0 (API level 11), the action bar is included in all -activities that use the {@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its -descendants), which is the default theme when either the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or -<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> -attribute is set to {@code "11"} or greater. For example:</p> +<p>As mentioned above, this guide focuses on how to use the {@link +android.support.v7.app.ActionBar} APIs in the support library. So before you can add the action +bar, you must set up your project with the <strong>appcompat v7</strong> support library by +following the instructions in the <a href="{@docRoot}tools/support-library/setup.html">Support +Library Setup</a>.</p> -<pre> -<manifest ... > - <uses-sdk android:minSdkVersion="4" - <b>android:targetSdkVersion="11"</b> /> - ... -</manifest> -</pre> +<p>Once your project is set up with the support library, here's how to add the action bar:</p> +<ol> + <li>Create your activity by extending {@link android.support.v7.app.ActionBarActivity}.</li> + <li>Use (or extend) one of the {@link android.support.v7.appcompat.R.style#Theme_AppCompat + Theme.AppCompat} themes for your activity. For example: + <pre><activity android:theme="@style/Theme.AppCompat.Light" ... ></pre> + </li> +</ol> -<p>In this example, the application requires a minimum version of API Level 4 (Android 1.6), but it -also targets API level 11 (Android 3.0). This way, when the application runs on Android 3.0 or -greater, the system applies the holographic theme to each activity, and thus, each activity includes -the action bar.</p> +<p>Now your activity includes the action bar when running on Android 2.2 (API level 7) or higher. +</p> -<p>If you want to use {@link android.app.ActionBar} APIs, such as to add navigation modes and modify -action bar styles, you should set the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> to {@code -"11"} or greater. If you want your app -to support older versions of Android, there are ways to use a limited set of {@link -android.app.ActionBar} APIs on devices that support API level 11 or higher, while still running -on older versions. See the sidebox for information about remaining backward-compatible.</p> +<div class="note"> +<p><b>On API level 11 or higher</b></p> +<p>The action bar is included in all activities that use the +{@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its +descendants), which is the default theme when either the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or +<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> +attribute is set to {@code "11"} or higher. If you don't want the action bar for an +activity, set the activity theme to {@link android.R.style#Theme_Holo_NoActionBar +Theme.Holo.NoActionBar}.</p> +</div> <h3 id="Removing">Removing the action bar</h3> -<p>If you don't want the action bar for a particular activity, set the activity theme to -{@link android.R.style#Theme_Holo_NoActionBar Theme.Holo.NoActionBar}. For example:</p> - -<pre> -<activity android:theme="@android:style/Theme.Holo.NoActionBar"> -</pre> - -<p>You can also hide the action bar at runtime by calling {@link android.app.ActionBar#hide}. For -example:</p> +<p>You can hide the action bar at runtime by calling {@link android.support.v7.app.ActionBar#hide}. +For example:</p> <pre> -ActionBar actionBar = {@link android.app.Activity#getActionBar()}; +ActionBar actionBar = {@link android.support.v7.app.ActionBarActivity#getSupportActionBar()}; actionBar.hide(); </pre> -<p>When the action bar hides, the system adjusts your activity layout to fill all the -screen space now available. You can bring the action bar back with {@link -android.app.ActionBar#show()}.</p> +<div class="note"> +<p><b>On API level 11 or higher</b></p> +<p>Get the {@link android.app.ActionBar} with the {@link android.app.Activity#getActionBar} +method.</p> +</div> + +<p>When the action bar hides, the system adjusts your layout to fill the +screen space now available. You can bring the action bar back by calling {@link +android.support.v7.app.ActionBar#show()}.</p> <p>Beware that hiding and removing the action bar causes your activity to re-layout in order to -account for the space consumed by the action bar. If your activity regularly hides and shows the -action bar (such as in the Android Gallery app), you might want to use overlay mode. Overlay mode -draws the action bar on top of your activity layout rather than in its own area of the screen. This +account for the space consumed by the action bar. If your activity often hides and shows the +action bar, you might want to enable <em>overlay mode</em>. Overlay mode +draws the action bar in front of your activity layout, obscuring the top portion. This way, your layout remains fixed when the action bar hides and re-appears. To enable overlay mode, -create a theme for your activity and set {@link android.R.attr#windowActionBarOverlay -android:windowActionBarOverlay} to {@code true}. For more information, see the section about <a +create a custom theme for your activity and set {@link +android.support.v7.appcompat.R.attr#windowActionBarOverlay +windowActionBarOverlay} to {@code true}. For more information, see the section below about <a href="#Style">Styling the Action Bar</a>.</p> -<p class="note"><strong>Tip:</strong> If you have a custom activity theme in which you'd like to -remove the action bar, set the {@link android.R.styleable#Theme_windowActionBar -android:windowActionBar} style property to {@code false}. However, if you remove the action bar -using a theme, then the window will not allow the action bar at all, so you cannot add it -later—calling {@link android.app.Activity#getActionBar()} will return null.</p> + +<h3 id="Logo">Using a logo instead of an icon</h3> + +<p>By default, the system uses your application icon in the action bar, as specified by the <a +href="{@docRoot}guide/topics/manifest/application-element.html#icon">{@code icon}</a> +attribute in the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code +<application>}</a> or <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a> element. However, if you also specify the <a +href="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code logo}</a> +attribute, then the action bar uses the logo image instead of the icon.</p> + +<p>A logo should usually be wider than the icon, but should not include unnecessary text. You +should generally use a logo only when it represents your brand in a traditional format that users +recognize. A good example is the YouTube app's logo—the logo represents the expected user +brand, whereas the app's icon is a modified version that conforms to the square requirement +for the launcher icon.</p> + <h2 id="ActionItems">Adding Action Items</h2> -<p>Sometimes you might want to give users immediate access to an item from the <a -href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a>. To do this, you can -declare that the menu item should appear in the action bar as an "action item." An action item can -include an icon and/or a text title. If a menu item does not appear as an action item, then the -system places it in the overflow menu. The overflow menu is revealed either by the device -<em>Menu</em> -button (if provided by the device) or an additional button in the action bar (if the device does not -provide the <em>Menu</em> button).</p> - -<div class="figure" style="width:359px"> - <img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" /> - <p class="img-caption"><strong>Figure 2.</strong> Two action items with icon and text titles, and -the overflow menu button.</p> +<div class="figure" style="width:340px"> + <img src="{@docRoot}images/ui/actionbar-item-withtext.png" width="340" alt="" /> + <p class="img-caption"><strong>Figure 2.</strong> Action bar with three action buttons and +the overflow button.</p> </div> -<p>When the activity first starts, the system populates the action bar and overflow menu by calling -{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} for your activity. As -discussed in the <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide, it's in -this callback method that you should inflate an XML <a -href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> that defines the -menu items. For example:</p> +<p>The action bar provides users access to the most important action +items relating to the app's current +context. Those that appear directly in the action bar with an icon and/or text are known +as <em>action buttons</em>. Actions that can't fit in the action bar or aren't +important enough are hidden in the action overflow. +The user can reveal a list of the other actions by pressing the overflow button +on the right side (or the device <em>Menu</em> button, if available).</p> + +<p>When your activity starts, the system populates the action items by calling your activity's +{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method. Use this +method to inflate a <a +href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> that defines all the +action items. For example, here's a menu resource defining a couple of menu items:</p> + +<p class="code-caption">res/menu/main_activity_actions.xml</p> +<pre> +<menu xmlns:android="http://schemas.android.com/apk/res/android" > + <item android:id="@+id/action_search" + android:icon="@drawable/ic_action_search" + android:title="@string/action_search"/> + <item android:id="@+id/action_compose" + android:icon="@drawable/ic_action_compose" + android:title="@string/action_compose" /> +</menu> +</pre> + +<p>Then in your activity's {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} +method, inflate the menu resource into the given {@link android.view.Menu} +to add each item to the action bar:</p> <pre> @Override public boolean onCreateOptionsMenu(Menu menu) { + // Inflate the menu items for use in the action bar MenuInflater inflater = getMenuInflater(); - inflater.inflate(R.menu.main_activity, menu); - return true; + inflater.inflate(R.menu.main_activity_actions, menu); + return super.onCreateOptionsMenu(menu); } </pre> -<p>In the XML file, you can request a menu item to appear as an action item by declaring {@code -android:showAsAction="ifRoom"} for the {@code <item>} element. This way, the menu item appears -in the action bar for quick access only <em>if there is room</em> available. If there's not -enough room, the item appears in the overflow menu.</p> +<p>To request that an item appear directly in the action bar +as an action button, include {@code +showAsAction="ifRoom"} in the {@code <item>} tag. For example:</p> -<p>If your menu item supplies both a title and an icon—with the {@code android:title} and -{@code android:icon} attributes—then the action item shows only the icon by default. If you -want to display the text title, add {@code "withText"} to the {@code android:showAsAction} +<pre> +<menu xmlns:android="http://schemas.android.com/apk/res/android" + <strong>xmlns:example.app="http://schemas.android.com/apk/res-auto"</strong> > + <item android:id="@+id/action_search" + android:icon="@drawable/ic_action_search" + android:title="@string/action_search" + <strong>example.app:showAsAction="ifRoom"</strong> /> + ... +</menu> +</pre> + +<p>If there's not enough room for the item in the action bar, it will appear in the action +overflow.</p> + + +<div class="note" id="XmlAttributes"> +<p><strong>Using XML attributes from the support library</strong></p> +Notice that the {@code showAsAction} attribute above uses a custom namespace defined in the +{@code <menu>} tag. This is necessary when using any XML attributes defined by the support +library, because these attributes do not exist in the Android framework on older devices. +So you must use your own namespace as a prefix for all attributes defined by the support library. +</p> +</div> + +<p>If your menu item supplies both a title and an icon—with the {@code title} and +{@code icon} attributes—then the action item shows only the icon by default. If you +want to display the text title, add {@code "withText"} to the {@code showAsAction} attribute. For example:</p> <pre> -<?xml version="1.0" encoding="utf-8"?> -<menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="@+id/menu_save" - android:icon="@drawable/ic_menu_save" - android:title="@string/menu_save" - <b>android:showAsAction="ifRoom|withText"</b> /> -</menu> +<item example.app:showAsAction="ifRoom|withText" ... /> </pre> <p class="note"><strong>Note:</strong> The {@code "withText"} value is a <em>hint</em> to the action bar that the text title should appear. The action bar will show the title when possible, but might not if an icon is available and the action bar is constrained for space.</p> -<p>When the user selects an action item, your activity receives a call to -{@link android.app.Activity#onOptionsItemSelected(MenuItem) -onOptionsItemSelected()}, passing the ID supplied by the {@code android:id} attribute—the same -callback received for all items in the options menu.</p> - -<p>It's important that you always define {@code android:title} for each menu item—even if you -don't declare that the title appear with the action item—for three reasons:</p> +<p>You should always define the {@code title} for each item even if you don't declare that +the title appear with the action item, for the following reasons:</p> <ul> <li>If there's not enough room in the action bar for the action item, the menu item appears -in the overflow menu and only the title appears.</li> +in the overflow where only the title appears.</li> <li>Screen readers for sight-impaired users read the menu item's title.</li> <li>If the action item appears with only the icon, a user can long-press the item to reveal a -tool-tip that displays the action item's title.</li> +tool-tip that displays the action title.</li> </ul> -<p>The {@code android:icon} is always optional, but recommended. For icon design recommendations, -see the <a href="{@docRoot}guide/practices/ui_guidelines/icon_design_action_bar.html">Action Bar -Icon</a> design guidelines.</p> - -<p class="note"><strong>Note:</strong> If you added the menu item from a fragment, via the {@link -android.app.Fragment} class's {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu} -callback, then the system calls the respective {@link -android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method for that -fragment when the user selects one of the fragment's items. However the activity gets a chance to -handle the event first, so the system calls {@link -android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} on the activity before -calling the same callback for the fragment.</p> - -<p>You can also declare an item to <em>"always"</em> appear as an action item, instead of being -placed in the overflow menu when space is limited. In most cases, you <strong>should not</strong> -force an item to appear in the action bar by using the {@code "always"} value. However, you might -need an item to always appear when it provides an <a href="#ActionView">action view</a> that does -not offer a default action for the overflow menu. Beware that too -many action items can create a cluttered UI and cause layout problems on devices with a narrow -screen. It's best to instead use {@code "ifRoom"} to request that an item appear in the action -bar, but allow the system to move it into the overflow menu when there's not enough room.</p> - -<p>For more information about creating the options menu that defines your action items, see the <a -href="{@docRoot}guide/topics/ui/menus.html#options-menu">Menus</a> developer guide.</p> - - - -<h3 id="ChoosingActionItems">Choosing your action items</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h4>Menu items vs. other app controls</h4> - <p>As a general rule, all items in the <a -href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> (let alone action items) -should have a global impact on the app, rather than affect only a small portion of the interface. -For example, if you have a multi-pane layout and one pane shows a video while another lists all -videos, the video player controls should appear within the pane containing the video (not in the -action bar), while the action bar might provide action items to share the video or save the video to -a favorites list.</p> - <p>So, even before deciding whether a menu item should appear as an action item, be sure that -the item has a global scope for the current activity. If it doesn't, then you should place it -as a button in the appropriate context of the activity layout.</p> -</div> -</div> +<p>The {@code icon} is optional, but recommended. For icon design recommendations, +see the <a href="{@docRoot}design/style/iconography.html#action-bar">Iconography</a> design +guide. You can also download a set of standard action bar icons (such as for Search or Discard) +from the <a href="{@docRoot}design/downloads/index.html">Downloads</a> page.</p> -<p>You should carefully choose which items from your options menu should appear as action items by -assessing a few key traits. In general, each action item should be <em>at least one</em> -of the following:</p> +<p>You can also use {@code "always"} to declare that an item always appear as an action button. +However, you <strong>should not</strong> force an item to appear in the action bar this +way. Doing so can create layout problems on devices with a narrow screen. It's best to instead +use {@code "ifRoom"} to request that an item appear in the action bar, but allow the system to move +it into the overflow when there's not enough room. However, it might be necessary to use this value +if the item includes an <a href="#ActionView">action view</a> that cannot be collapsed and +must always be visible to provide access to a critical feature.</p> -<ol> - <li><strong>Frequently used</strong>: It's an action that your users need seven out of ten visits -or they use it several times in a row. - <p>Example frequent actions: "New message" in the Messaging app and -"Search" on Google Play.</p> - </li> - - <li><strong>Important</strong>: It's an action that you need users to easily discover or, if it's -not frequently used, it's important that it be effortless to perform in the few cases that users do -need it. - <p>Example important actions: "Add network" in Wi-Fi settings and "Switch to camera" in the -Gallery app.</p> - </li> - <li><strong>Typical</strong>: It's an action that is typically provided in the action bar in -similar apps, so your users expect to find it in yours. - <p>Example typical actions: "Refresh" in an email or social app, and "New contact" in the -People app.</p> -</ol> -<p>If you believe that more than four of your menu items can be justified as action items, then you -should carefully consider their relative level of importance and try to set no more than four as -action items (and do so using the {@code "ifRoom"} value to allow the system to put some back in the -overflow menu when space is limited on smaller screens). Even if space is available on a wide -screen, you should not create a long stream of action items that clutter the UI and appear like a -desktop toolbar, so keep the number of action items to a minimum.</p> -<p>Additionally, the following actions should never appear as action items: Settings, Help, -Feedback, or similar. Always keep them in the overflow menu.</p> +<h3 id="ActionEvents">Handling clicks on action items</h3> -<p class="note"><strong>Note:</strong> Remember that not all devices provide a dedicated hardware -button for Search, so if it's an important feature in your app, it should always appear as an -action item (and usually as the first item, especially if you offer it with an <a -href="#ActionView">action view</a>).</p> +<p>When the user presses an action, the system calls your activity's {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method. Using the +{@link android.view.MenuItem} passed to this method, you can identify the action by calling {@link +android.view.MenuItem#getItemId()}. This returns the unique ID provided by the {@code <item>} +tag's {@code id} attribute so you can perform the appropriate action. For example:</p> +<pre> +@Override +public boolean onOptionsItemSelected(MenuItem item) { + // Handle presses on the action bar items + switch (item.getItemId()) { + case R.id.action_search: + openSearch(); + return true; + case R.id.action_compose: + composeMessage(); + return true; + default: + return super.onOptionsItemSelected(item); + } +} +</pre> +<p class="note"><strong>Note:</strong> If you inflate menu items from a fragment, via the {@link +android.app.Fragment} class's {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} +callback, the system calls {@link +android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} for that +fragment when the user selects one of those items. However, the activity gets a chance to +handle the event first, so the system first calls {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} on the activity, +before calling the same callback for the fragment. To ensure that any fragments in the +activity also have a chance to handle the callback, always pass the call to the superclass +as the default behavior instead of returning {@code false} when you do not handle the item.</p> + + + +<div class="figure" style="width:420px;margin-top:0"> +<img src="{@docRoot}images/ui/actionbar-splitaction@2x.png" alt="" width="420"/> +<p class="img-caption"><strong>Figure 3.</strong> Mock-ups showing an action bar with +tabs (left), then with split action bar (middle); and with the app icon and title disabled +(right).</p> +</p> +</div> <h3 id="SplitBar">Using split action bar</h3> -<p>When your application is running on Android 4.0 (API level 14) and higher, there's an extra mode -available for the action bar called "split action bar." When you enable split action bar, a separate -bar appears at the bottom of the screen to display all action items when the activity is running on -a narrow screen (such as a portrait-oriented handset). Splitting the action bar to separate -the action items ensures that a reasonable amount of space is available to display all your action +<p>Split action bar provides a separate +bar at the bottom of the screen to display all action items when the activity is running on +a narrow screen (such as a portrait-oriented handset).</p> + +<p>Separating the action items this way +ensures that a reasonable amount of space is available to display all your action items on a narrow screen, while leaving room for navigation and title elements at the top.</p> -<p>To enable split action bar, simply add {@code uiOptions="splitActionBarWhenNarrow"} to your +<p>To enable split action bar when using the support library, you must do two things:</p> +<ol> + <li>Add {@code uiOptions="splitActionBarWhenNarrow"} to your <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> or <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> -manifest element.</p> +manifest element. This attribute is understood only by API level 14 and higher (it is ignored +by older versions). + <li>For older versions, create a custom theme that extends one of the {@link + android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} themes, and include + the {@link android.support.v7.appcompat.R.attr#windowSplitActionBar windowSplitActionBar} style + set {@code true}. For example: + <p class="code-caption">res/values/styles.xml</p> + <pre> +<style name="MyAppTheme" parent="Theme.AppCompat.Light"> + <item name="windowSplitActionBar">true<item> +</style> +</pre> -<p>Be aware that Android adjusts the action bar's appearance in a variety of ways, based on the -current screen size. Using split action bar is just one option that you can enable to allow the -action bar to further optimize the user experience for different screen sizes. In doing so, you -may also allow the action bar to collapse navigation tabs into the main action bar. That is, if you -use <a href="#Tabs">navigation tabs</a> in your action bar, once the action items are -separated on a narrow screen, the navigation tabs may be able to fit into the main action bar rather -than be separated into the "stacked action bar." Specifically, if you've disabled the action bar -icon and title (with {@link android.app.ActionBar#setDisplayShowHomeEnabled -setDisplayShowHomeEnabled(false)} and {@link android.app.ActionBar#setDisplayShowTitleEnabled -setDisplayShowTitleEnabled(false)}), then the navigation tabs collapse into the main action bar, as -shown by the second device in figure 3.</p> + <p>Then set this as your activity theme:</p> -<img src="{@docRoot}images/practices/actionbar-phone-splitaction.png" alt=""/> -<p class="img-caption"><strong>Figure 3.</strong> Mock-ups of split action bar with navigation tabs -on the left; with the app icon and title disabled on the right.</p> + <p class="code-caption">AndroidManifest.xml</p> + <pre> +<manifest ...> + <activity android:theme="@style/MyAppTheme" ...> + ... +</manifest ...> +</pre> + </li> +</ol> -<p class="note"><strong>Note:</strong> Although the {@link android.R.attr#uiOptions -android:uiOptions} attribute was added in Android 4.0 (API level 14), you can safely include it in -your application even if your <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is set to -a value lower than {@code "14"} to remain compatible with older versions of Android. When running on -older versions, the system simply ignores the XML attribute because it doesn't understand it. The -only condition to including it in your manifest is that you must compile your application against a -platform version that supports API level 14 or higher. Just be sure that you don't openly use other -APIs in your application code that aren't supported by the version declared by your <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> -attribute—only XML attributes are safely ignored by older platforms.</p> +<p>Using split action bar also allows <a href="#Tabs">navigation tabs</a> to collapse into the +main action bar if you remove the icon and title (as shown on the right in figure 3). +To create this effect, disable the action bar +icon and title with {@link android.support.v7.app.ActionBar#setDisplayShowHomeEnabled +setDisplayShowHomeEnabled(false)} and {@link +android.support.v7.app.ActionBar#setDisplayShowTitleEnabled setDisplayShowTitleEnabled(false)}.</p> -<h2 id="Home">Using the App Icon for Navigation</h2> +<h2 id="Home">Navigating Up with the App Icon</h2> +<a class="notice-designers" href="{@docRoot}design/patterns/navigation.html"> + <div> + <h3>Design Guide</h3> + <p>Navigation with Back and Up</p> + </div> +</a> -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h2>Using a logo instead of icon</h2> -<p>By default, the system uses your application icon in the action bar, as specified by the <a -href="{@docRoot}guide/topics/manifest/application-element.html#icon">{@code android:icon}</a> -attribute in the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code -<application>}</a> or <a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code -<activity>}</a> element. However, if you also specify the <a -href="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code android:logo}</a> -attribute, then the action bar uses the logo image instead of the icon.</p> -<p>A logo should usually be wider than the icon, but should not include unnecessary text. You -should generally use a logo only when it represents your brand in a traditional format that users -recognize. A good example is the YouTube app's logo—the logo represents the expected user -brand, whereas the app's icon is a modified version that conforms to the square requirement.</p> -</div> +<div class="figure" style="width:240px"> + <img src="{@docRoot}images/ui/actionbar-up.png" width="240" alt="" /> + <p class="img-caption"><strong>Figure 4.</strong> The <em>Up</em> button in Gmail.</p> </div> +<p>Enabling the app icon as an <em>Up</em> button allows the user to navigate your app based +on the hierarchical relationships between screens. For instance, if screen A displays a list of +items, and selecting an item leads to screen B, then +screen B should include the <em>Up</em> button, which returns to screen A.</p> -<p>By default, your application icon appears in the action bar on the left side. If you'd like, -you can enable the icon to behave as an action item. In response to user action on the icon, your -application should do one of two things:</p> - -<ul> - <li>Go to the application "home" activity, or</li> - <li>Navigate "up" the application's structural hierarchy</li> -</ul> - -<p>When the user touches the icon, the system calls your activity's {@link -android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method with the {@code -android.R.id.home} ID. In response, you should either start the home activity or -take the user one step up in your application's structural hierarchy.</p> - -<p>If you respond to the application icon by returning to the home activity, you should include -the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag in the {@link -android.content.Intent}. With this flag, if the activity you're starting already exists in the -current task, then all activities on top of it are destroyed and it is brought to the front. -Adding this flag is often important because going "home" is an action that's equivalent to "going -back" and you should usually not create a new instance of the home activity. Otherwise, you -might end up with a long stack of activities in the current task with multiple instances of the -home activity.</p> +<p class="note"><strong>Note:</strong> Up navigation is distinct from the back navigation provided +by the system <em>Back</em> button. The <em>Back</em> button is used to navigate in reverse +chronological order through the history of screens the user has recently worked with. It is +generally based on the temporal relationships between screens, rather than the app's hierarchy +structure (which is the basis for up navigation).</p> -<p>For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected -onOptionsItemSelected()} that returns to the application's "home" activity:</p> +<p>To enable the app icon as an <em>Up</em> button, call {@link +android.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}. +For example:</p> <pre> @Override -public boolean onOptionsItemSelected(MenuItem item) { - switch (item.getItemId()) { - case android.R.id.home: - // app icon in action bar clicked; go home - Intent intent = new Intent(this, HomeActivity.class); - intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP); - startActivity(intent); - return true; - default: - return super.onOptionsItemSelected(item); - } +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_details); + + ActionBar actionBar = getSupportActionBar(); + actionBar.setDisplayHomeAsUpEnabled(true); + ... } </pre> -<p>In case the user can enter the current activity from another application, you might also want to -add the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag. This flag ensures that, when the -user navigates either "home" or "up", the new activity is <strong>not</strong> added to the current -task, but instead started in a task that belongs to your application. For example, if the user -starts an activity in your application through an intent invoked by another application, then -selects the action bar icon to navigate home or up, the {@link -android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag starts the activity in a task that belongs to -your application (not the current task). The system either starts a new task with your new activity -as the root activity or, if an existing task exists in the background with an instance of that -activity, then that task is brought forward and the target activity receives {@link -android.app.Activity#onNewIntent onNewIntent()}. So if your activity accepts intents from other -applications (it declares any generic intent filters), you should usually add the {@link -android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag to the intent:</p> +<p>Now the icon in the action bar appears with the <em>Up</em> caret (as shown in figure 4). +However, it won't do anything by default. To specify the activity to open when the +user presses <em>Up</em> button, you have two options:</p> +<ul> + <li><b>Specify the parent activity in the manifest file.</b> + <p>This is the best option when <strong>the parent activity is always the same</strong>. By +declaring in the manifest which activity is the parent, the action bar automatically performs the +correct action when the user presses the <em>Up</em> button.</p> + + <p>Beginning in Android 4.1 (API level 16), you can declare the parent with the <a href= +"{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code parentActivityName}</a> +attribute in the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a> element.</p> + <p>To support older devices with the support library, also +include a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code +<meta-data>}</a> element that specifies +the parent activity as the value for {@code android.support.PARENT_ACTIVITY}. For example:</p> <pre> -intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK); +<application ... > + ... + <!-- The main/home activity (has no parent activity) --> + <activity + android:name="com.example.myfirstapp.MainActivity" ...> + ... + </activity> + <!-- A child of the main activity --> + <activity + android:name="com.example.myfirstapp.DisplayMessageActivity" + android:label="@string/title_activity_display_message" + android:parentActivityName="com.example.myfirstapp.MainActivity" > + <!-- Parent activity meta-data to support API level 7+ --> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value="com.example.myfirstapp.MainActivity" /> + </activity> +</application> </pre> -<p>For more information about these flags and other back stack behaviors, read the <a -href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> -developer guide.</p> - -<p class="note"><strong>Note:</strong> If you're using the icon to navigate to the home -activity, beware that beginning with Android 4.0 (API level 14), you must explicitly enable the -icon as an action item by calling {@link android.app.ActionBar#setHomeButtonEnabled -setHomeButtonEnabled(true)} (in previous versions, the icon was enabled as an action item by -default).</p> - - - -<h3 id="Up">Navigating up</h3> - -<div class="figure" style="width:230px;margin-top:-1em"> - <img src="{@docRoot}images/ui/actionbar-logo.png" alt="" /> - <p class="img-caption"><strong>Figure 4.</strong> The Email app's standard icon -(left) and the "navigate up" icon (right). The system automatically adds the "up" indicator.</p> -</div> - -<p>As a supplement to traditional "back" navigation—which takes the user to the previous -screen in the task history—you can enable the action bar icon to offer "up" -navigation, which should take the user one step up in your application's structural hierarchy. For -instance, if the current screen is somewhere deep in the hierarchy of the application, touching the -app icon should navigate upward one level, to the parent of the current screen.</p> - -<p>For example, figure 5 illustrates how the BACK button behaves when the user navigates from one -application to an activity belonging to a different application (specifically, when composing an -email to a person selected from the People app).</p> - -<img src="{@docRoot}images/ui/actionbar-navigate-back.png" alt="" /> -<p class="img-caption"><strong>Figure 5.</strong> The BACK button behavior -after entering the Email app from the People (or Contacts) app.</p> - -<p>However, if the user wants to stay within the email application after composing the email, -up navigation allows the user to navigate upward in the email application, rather than go back -to the previous activity. Figure 6 illustrates this scenario, in which the user again comes into -the email application, but presses the action bar icon to navigate up, rather than back.</p> - -<img src="{@docRoot}images/ui/actionbar-navigate-up.png" alt="" /> -<p class="img-caption"><strong>Figure 6.</strong> Example behavior for UP navigation after -entering the Email app from the People app.</p> - -<div class="note design"> -<p><strong>Navigation Design</strong></p> - <p>For more about how <em>Up</em> and <em>Back</em> navigation differ, read Android Design's <a -href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> -</div> + <p>Once the parent activity is specified in the manifest like this and you enable the <em>Up</em> + button with {@link +android.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}, your work +is done and the action bar properly navigates up.</p> + </li> -<p>To enable the icon for up navigation (which displays the "up" indicator next to the icon), call -{@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled(true)} on your -{@link android.app.ActionBar}:</p> -<pre> -protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); + <li><strong>Or, override {@link +android.support.v7.app.ActionBarActivity#getSupportParentActivityIntent()} and {@link +android.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack +onCreateSupportNavigateUpTaskStack()} in your activity</strong>.</li> + + <p>This is appropriate when <strong>the parent activity may be different</strong> depending + on how the user arrived at the current screen. That is, if there are many paths that the user + could have taken to reach the current screen, the <em>Up</em> button should navigate + backward along the path the user actually followed to get there.</p> + + <p>The system calls {@link +android.support.v7.app.ActionBarActivity#getSupportParentActivityIntent()} when the user presses +the <em>Up</em> button while navigating your app (within your app's own task). If the activity that +should open upon up navigation differs depending on how the user arrived at the current location, +then you should override this method to return the {@link +android.content.Intent} that starts the appropriate parent activity.</p> + + <p>The system calls {@link +android.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack +onCreateSupportNavigateUpTaskStack()} for your activity when the user presses the <em>Up</em> +button while your activity is running in a task that does <em>not</em> belong to your app. Thus, +you must use the {@link android.support.v4.app.TaskStackBuilder} passed to this method to construct +the appropriate back stack that should be synthesized when the user navigates up.</p> + + <p>Even if you override {@link +android.support.v7.app.ActionBarActivity#getSupportParentActivityIntent()} to specify up navigation +as the user navigates your app, you can avoid the need to implement {@link +android.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack +onCreateSupportNavigateUpTaskStack()} by declaring "default" parent activities in the manifest file +as shown above. Then the default implementation of {@link +android.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack +onCreateSupportNavigateUpTaskStack()} will synthesize a back stack based on the parent activities +declared in the manifest.</p> - setContentView(R.layout.main); - ActionBar actionBar = getActionBar(); - actionBar.setDisplayHomeAsUpEnabled(true); - ... -} -</pre> - -<p>When the user touches the icon, the system calls your activity's {@link -android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method with the {@code -android.R.id.home} ID, as shown in the above section about <a href="#Home">Using the App Icon -for Navigation</a>.</p> - -<p>Remember to use the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag in the {@link -android.content.Intent}, so that you don't create a new instance of the parent activity if one -already exists. For instance, if you don't use the {@link -android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag, then after navigating up, the BACK button will -actually take the user "forward", with respect to the application structure, which would be -strange.</p> + </li> +</ul> -<p class="note"><strong>Note:</strong> If there are many paths that the user could have taken to -reach the current activity within your application, the up icon should navigate backward along the -path the user actually followed to get to the current activity.</p> +<p class="note"><strong>Note:</strong> +If you've built your app hierarchy using a series of fragments instead of multiple +activities, then neither of the above options will work. Instead, to navigate up through your +fragments, override {@link android.support.v7.app.ActionBarActivity#onSupportNavigateUp()} +to perform the appropriate fragment transaction—usually by popping +the current fragment from the back stack by calling {@link +android.support.v4.app.FragmentManager#popBackStack()}.</p> +<p>For more information about implementing <em>Up</em> navigation, read +<a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up Navigation</a>.</p> <h2 id="ActionView">Adding an Action View</h2> -<div class="figure" style="width:300px;margin-top:-1em"> - <img src="/images/ui/actionbar-searchview.png" alt="" /> - <p class="img-caption"><strong>Figure 7.</strong> An action bar with a collapsed action -view for Search (top), then expanded action view with the <code><a -href="/reference/android/widget/SearchView.html">SearchView</a></code> widget (bottom).</p> +<div class="figure" style="width:340px"> +<img src="/images/ui/actionbar-searchview@2x.png" alt="" width="340" /> +<p class="img-caption"><strong>Figure 5.</strong> An action bar with a collapsible +{@link android.support.v7.widget.SearchView}.</p> </div> -<p>An action view is a widget that appears in the action bar as a substitute for an action item's -button. For example, if you have an item in the options menu for "Search," you can add an action -view that replaces the button with a {@link android.widget.SearchView} widget, as shown in figure -7.</p> +<p>An <em>action view</em> is a widget that appears in the action bar as a substitute for an action +button. An action view provides fast access to rich actions without changing activities or +fragments, and without replacing the action bar. For example, if you have an action for Search, you +can add an action view to +embeds a {@link android.support.v7.widget.SearchView} widget in the action bar, as shown in figure +5.</p> -<p>To declare an action view for an item in your <a -href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, use either the {@code -android:actionLayout} or {@code android:actionViewClass} attribute to specify either a layout -resource or widget class to use, respectively. For example:</p> +<p>To declare an action view, use either the {@code +actionLayout} or {@code actionViewClass} attribute to specify either a layout +resource or widget class to use, respectively. For example, here's how to add +the {@link android.support.v7.widget.SearchView} widget:</p> <pre> <?xml version="1.0" encoding="utf-8"?> -<menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="@+id/menu_search" - android:title="@string/menu_search" - android:icon="@drawable/ic_menu_search" - android:showAsAction="ifRoom|collapseActionView" - <b>android:actionViewClass="android.widget.SearchView"</b> /> +<menu xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:example.app="http://schemas.android.com/apk/res-auto" > + <item android:id="@+id/action_search" + android:title="@string/action_search" + android:icon="@drawable/ic_action_search" + example.app:showAsAction="ifRoom|collapseActionView" + <b>example.app:actionViewClass="android.support.v7.widget.SearchView"</b> /> </menu> </pre> -<p>Notice that the {@code android:showAsAction} attribute also includes {@code -"collapseActionView"}. This is optional and declares that the action view should be collapsed into a -button. When the user selects the button, the action view expands. Otherwise, the action view is -visible by default and might consume valuable action bar space even when the user is not using it. -For more information, see the next section about <a href="#ActionViewCollapsing">Handling -collapsible action views</a>.</p> +<p>Notice that the {@code showAsAction} attribute also includes the {@code "collapseActionView"} +value. This is optional and declares that the action view should be collapsed into a +button. (This behavior is explained further in the following section about +<a href="#ActionViewCollapsing">Handling collapsible action views</a>.)</p> + +<p>If you need to configure the action view (such as to add event listeners), you can do so during +the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You can +acquire the action view object by calling the static method {@link +android.support.v4.view.MenuItemCompat#getActionView MenuItemCompat.getActionView()} and passing it +the corresponding {@link android.view.MenuItem}. For example, the search widget from the above +sample is acquired like this:</p> -<p>If you need to add some event hooks to your action view, you can do so during the {@link -android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You can acquire elements -in an action view by calling {@link android.view.Menu#findItem findItem()} with the ID of the menu -item, then call {@link android.view.MenuItem#getActionView}. For -example, the search widget from the above sample is acquired like this:</p> <pre> @Override public boolean onCreateOptionsMenu(Menu menu) { - getMenuInflater().inflate(R.menu.options, menu); - SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView(); + getMenuInflater().inflate(R.menu.main_activity_actions, menu); + MenuItem searchItem = menu.findItem(R.id.action_search); + SearchView searchView = (SearchView) MenuItemCompat.getActionView(searchItem); // Configure the search info and add any event listeners ... return super.onCreateOptionsMenu(menu); } </pre> +<div class="note"> +<p><b>On API level 11 or higher</b></p> +<p>Get the action view by calling {@link android.view.MenuItem#getActionView} on the +corresponding {@link android.view.MenuItem}:</p> +<pre>menu.findItem(R.id.action_search).getActionView()</pre> +</div> + <p>For more information about using the search widget, see <a href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</a>.</p> -<h3 id="ActionViewCollapsing">Handling collapsible action views</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h3>Supporting Android 3.0 with an action view</h3> - <p>The {@code "collapseActionView"} option was added with Android 4.0 (API level 14). However, if -your application supports older versions, you should -still declare {@code "collapseActionView"} in order to better support smaller screens. -Devices running Android 4.0 and higher will show the action view collapsed, while older versions -work as designed otherwise.</p> - <p>Adding this value requires that you set your build target to Android 4.0 or higher in order to -compile. Older versions of Android ignore the {@code "collapseActionView"} value because they don't -understand it. Just be sure not to use other APIs in your source code that are not supported in the -version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code -minSdkVersion}</a>, unless you add the appropriate version check at runtime.</p> -</div> -</div> +<h3 id="ActionViewCollapsing">Handling collapsible action views</h3> -<p>Action views allow you to provide fast access to rich actions without changing activities or -fragments, or replacing the action bar. However, it might not be appropriate to make an action view -visible by default. To preserve the action bar space (especially when running on smaller screens), -you can collapse your action view into an action item button. When the user selects the -button, the action view appears in the action bar. When collapsed, the system might place the item -into the overflow menu if you've defined {@code android:showAsAction} with {@code "ifRoom"}, but the -action view still appears in the action bar when the user selects the item. You can make your action -view collapsible by adding {@code "collapseActionView"} to the {@code android:showAsAction} +<p>To preserve the action bar space, you can collapse your action view into an action button. +When collapsed, the system might place the action +into the action overflow, but the +action view still appears in the action bar when the user selects it. You can make your action +view collapsible by adding {@code "collapseActionView"} to the {@code showAsAction} attribute, as shown in the XML above.</p> -<p>Because the system will expand the action view when the user selects the item, you +<p>Because the system expands the action view when the user selects the action, you <em>do not</em> need to respond to the item in the {@link -android.app.Activity#onOptionsItemSelected onOptionsItemSelected} callback. The system still calls -{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} when the user selects it, -but the system will always expand the action view unless you return {@code true} (indicating -you've handled the event instead).</p> - -<p>The system also collapses your action view when the user selects the "up" icon in the action -bar or presses the BACK button.</p> - -<p>If necessary, you can expand or collapse the action view in your own code by calling {@link -android.view.MenuItem#expandActionView()} and {@link android.view.MenuItem#collapseActionView()} on -the {@link android.view.MenuItem}.</p> - -<p class="note"><strong>Note:</strong> Although collapsing your action view is optional, we -recommend that you always collapse your action view if it includes {@link -android.widget.SearchView}. Also be aware that some devices provide a dedicated SEARCH button and -you should expand your search action view if the user presses the SEARCH button. Simply override -your activity's {@link android.app.Activity#onKeyUp onKeyUp()} callback method, listen for the -{@link android.view.KeyEvent#KEYCODE_SEARCH} event, then call {@link -android.view.MenuItem#expandActionView()}.</p> +android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback. The system still calls +{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}, but if +you return {@code true} (indicating you've handled the event instead), then the +action view will <em>not</em> expand.</p> + +<p>The system also collapses your action view when the user presses the <em>Up</em> button +or <em>Back</em> button.</p> <p>If you need to update your activity based on the visibility of your action view, you can receive -callbacks when it's expanded and collapsed by defining an {@link -android.view.MenuItem.OnActionExpandListener OnActionExpandListener} and registering it with {@link -android.view.MenuItem#setOnActionExpandListener setOnActionExpandListener()}. For example:</p> +callbacks when the action is expanded and collapsed by defining an {@link +android.support.v4.view.MenuItemCompat.OnActionExpandListener OnActionExpandListener} and +passing it to {@link android.support.v4.view.MenuItemCompat#setOnActionExpandListener +setOnActionExpandListener()}. For example:</p> + <pre> @Override @@ -708,7 +651,9 @@ public boolean onCreateOptionsMenu(Menu menu) { MenuItem menuItem = menu.findItem(R.id.actionItem); ... - menuItem.setOnActionExpandListener(new OnActionExpandListener() { + // When using the support library, the setOnActionExpandListener() method is + // static and accepts the MenuItem object as an argument + MenuItemCompat.setOnActionExpandListener(menuItem, new OnActionExpandListener() { @Override public boolean onMenuItemActionCollapse(MenuItem item) { // Do something when collapsed @@ -729,165 +674,168 @@ public boolean onCreateOptionsMenu(Menu menu) { <h2 id="ActionProvider">Adding an Action Provider</h2> -<div class="figure" style="width:200px"> - <img src="{@docRoot}images/ui/actionbar-shareaction.png" alt="" /> - <p class="img-caption"><strong>Figure 8.</strong> Screenshot from the Gallery app, with the - {@link android.widget.ShareActionProvider} submenu expanded to show share targets.</p> +<div class="figure" style="width:240px"> + <img src="{@docRoot}images/ui/actionbar-shareaction@2x.png" alt="" width="240" /> + <p class="img-caption"><strong>Figure 6.</strong> An action bar with + {@link android.widget.ShareActionProvider} expanded to show share targets.</p> </div> -<p>Similar to an <a href="#ActionView">action view</a>, an action provider (defined by the {@link -android.view.ActionProvider} class) replaces an action item with a customized layout, but it also -takes control of all the item's behaviors. When you declare an action provider for a menu -item in the action bar, it not only controls the appearance of the item in the action bar with a -custom layout, but also handles the default event for the menu item when it appears in the overflow -menu. It can also provide a submenu from either the action bar or the overflow menu.</p> - -<p>For example, the {@link android.widget.ShareActionProvider} is an extension of {@link -android.view.ActionProvider} that facilitates a “share" action by showing a list of available share -targets from the action bar. Instead of using a -traditional action item that invokes the {@link android.content.Intent#ACTION_SEND} intent, you can -declare an instance of {@link android.widget.ShareActionProvider} to handle an action item. This -action provider presents an action view with a drop-down list of applications that handle -the {@link android.content.Intent#ACTION_SEND} intent, even when the menu item appears in the -overflow menu. Hence, when you use an action provider such as this one, you don't -have to handle user events on the menu item.</p> - -<p>To declare an action provider for an action item, define the {@code android:actionProviderClass} -attribute for the appropriate the {@code <item>} element in your <a -href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, using the -fully-qualified class name of the action provider. For example:</p> +<p>Similar to an <a href="#ActionView">action view</a>, an <em>action provider</em> +replaces an action button with a customized layout. However, +unlike an action view, an action provider takes control of all the action's behaviors +and an action provider can display a submenu when pressed.</p> -<pre> -<?xml version="1.0" encoding="utf-8"?> -<menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="@+id/menu_share" - android:title="@string/share" - android:showAsAction="ifRoom" - <strong>android:actionProviderClass="android.widget.ShareActionProvider"</strong> /> - ... -</menu> -</pre> +<p>To declare an action provider, supply the {@code actionViewClass} attribute in the +menu {@code <item>} tag with a fully-qualified class name for an +{@link android.support.v4.view.ActionProvider}.</p> -<p>In this example, the {@link android.widget.ShareActionProvider} is used as the action provider. -At this point, the action provider officially takes control of the menu item and handles both -its appearance and behavior in the action bar and its behavior in the overflow menu. You must -still provide a text title for the item to be used in the overflow menu.</p> +<p>You can build your own action provider by extending the {@link +android.support.v4.view.ActionProvider} class, but Android provides some pre-built action providers +such as {@link android.support.v7.widget.ShareActionProvider}, which facilitates a "share" action +by showing a list of possible apps for sharing directly in the action bar (as shown in figure +6).</p> -<p>Although the action provider can perform the default action for the menu item when it appears in -the overflow menu, your activity (or fragment) can override that behavior by -also handling the click event from the {@link android.app.Activity#onOptionsItemSelected -onOptionsItemSelected()} callback method. If you do not handle the event in that callback, then -the action provider receives the {@link android.view.ActionProvider#onPerformDefaultAction()} -callback to handle the event. However, if the action provider provides a submenu, then your -activity will not receive the {@link android.app.Activity#onOptionsItemSelected -onOptionsItemSelected()} callback, because the submenu is shown instead of invoking the default -menu item behavior when selected.</p> +<p>Because each {@link android.support.v4.view.ActionProvider} class defines its own action +behaviors, you don't need to listen for the action in the {@link +android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method. If necessary though, +you can still listen for the click event in the {@link android.app.Activity#onOptionsItemSelected +onOptionsItemSelected()} method in case you need to simultaneously perform another action. But be +sure to return {@code false} so that the the action provider still receives the {@link +android.support.v4.view.ActionProvider#onPerformDefaultAction()} callback to perform its intended +action.</p> + + +<p>However, if the action provider provides a submenu of actions, then your +activity does not receive a call to {@link android.app.Activity#onOptionsItemSelected +onOptionsItemSelected()} when the user opens the list or selects one of the submenu items.</p> <h3 id="ShareActionProvider">Using the ShareActionProvider</h3> -<p>If you want to provide a "share" action in your action bar by leveraging other applications -installed on the device (for example, to share a photo using a messaging or social app), then using -{@link android.widget.ShareActionProvider} is an effective way to do so, rather than adding an -action item that invokes the {@link android.content.Intent#ACTION_SEND} intent. When -you use {@link android.widget.ShareActionProvider} for an action item, it presents an action view -with a drop-down list of applications that handle the {@link android.content.Intent#ACTION_SEND} -intent (as shown in figure 8).</p> +<p>To add a "share" action with {@link android.support.v7.widget.ShareActionProvider}, +define the {@code actionProviderClass} for an {@code <item>} tag with +the {@link android.support.v7.widget.ShareActionProvider} class. For example:</p> -<p>All the logic for creating the submenu, populating it with share targets, and handling click -events (including when the item appears in the overflow menu) is implemented by the {@link -android.widget.ShareActionProvider}—the only code you need to write is to declare the action -provider for the menu item and specify the share intent.</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:example.app="http://schemas.android.com/apk/res-auto" > + <item android:id="@+id/action_share" + android:title="@string/share" + example.app:showAsAction="ifRoom" + <strong>example.app:actionProviderClass="android.support.v7.widget.ShareActionProvider"</strong> + /> + ... +</menu> +</pre> -<p>By default, the {@link android.widget.ShareActionProvider} retains a ranking for each -share target based on how often the user selects each one. The share targets used more frequently -appear at the top of the drop-down list and the target used most often appears directly in the -action bar as the default share target. By default, the ranking information is -saved in a private file with a name specified by {@link -android.widget.ShareActionProvider#DEFAULT_SHARE_HISTORY_FILE_NAME}. If you use the {@link -android.widget.ShareActionProvider} or an extension of it for only one type of action, then you -should continue to use this default history file and there's nothing you need to do. However, if you -use {@link android.widget.ShareActionProvider} or an extension of it for multiple actions with -semantically different meanings, then each {@link android.widget.ShareActionProvider} should specify -its own history file in order to maintain its own history. To specify a -different history file for the {@link android.widget.ShareActionProvider}, call {@link -android.widget.ShareActionProvider#setShareHistoryFileName setShareHistoryFileName()} and provide -an XML file name (for example, {@code "custom_share_history.xml"}).</p> - -<p class="note"><strong>Note:</strong> Although the {@link android.widget.ShareActionProvider} ranks -share targets based on frequency of use, the behavior is extensible and extensions of {@link -android.widget.ShareActionProvider} can perform different behaviors and ranking based on the history -file (if appropriate).</p> - -<p>To add {@link android.widget.ShareActionProvider}, simply define the {@code -android:actionProviderClass} attribute with {@code "android.widget.ShareActionProvider"}, as shown -in the XML example above. The only thing left to do is define -the {@link android.content.Intent} you want to use for sharing. To do so, you must call {@link -android.view.MenuItem#getActionProvider} to retrieve the {@link android.widget.ShareActionProvider} -that's associated with a {@link android.view.MenuItem}, then call {@link -android.widget.ShareActionProvider#setShareIntent setShareIntent()}.</p> - -<p>If the format for the share intent depends on the selected item or other variables that change -during the activity lifecycle, you should save the {@link android.widget.ShareActionProvider} in a -member field and update it by calling {@link android.widget.ShareActionProvider#setShareIntent -setShareIntent()} as necessary. For example:</p> +<p>Now the action provider takes control of the action item and handles both +its appearance and behavior. But you must +still provide a title for the item to be used when it appears in the action overflow.</p> + +<p>The only thing left to do is define +the {@link android.content.Intent} you want to use for sharing. To do so, edit +your {@link +android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method to call {@link +android.support.v4.view.MenuItemCompat#getActionProvider MenuItemCompat.getActionProvider()} +and pass it the {@link android.view.MenuItem} holding the action provider. Then call {@link +android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} on the +returned {@link android.support.v7.widget.ShareActionProvider} and pass it an +{@link android.content.Intent#ACTION_SEND} intent with the appropriate content attached.</p> + +<p>You should call {@link +android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} once during {@link +android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} to initialize the share action, +but because the user context might change, you must update the intent any time the shareable +content changes by again calling {@link +android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()}.</p> + +<p>For example:</p> <pre> private ShareActionProvider mShareActionProvider; -... @Override public boolean onCreateOptionsMenu(Menu menu) { - mShareActionProvider = (ShareActionProvider) menu.findItem(R.id.menu_share).getActionProvider(); + getMenuInflater().inflate(R.menu.main_activity_actions, menu); - // If you use more than one ShareActionProvider, each for a different action, - // use the following line to specify a unique history file for each one. - // mShareActionProvider.setShareHistoryFileName("custom_share_history.xml"); + // Set up ShareActionProvider's default share intent + MenuItem shareItem = menu.findItem(R.id.action_share); + mShareActionProvider = (ShareActionProvider) + MenuItemCompat.getActionProvider(shareItem); + mShareActionProvider.setShareIntent(getDefaultIntent()); - // Set the default share intent - mShareActionProvider.setShareIntent(getDefaultShareIntent()); + return super.onCreateOptionsMenu(menu); +} - return true; +/** Defines a default (dummy) share intent to initialize the action provider. + * However, as soon as the actual content to be used in the intent + * is known or changes, you must update the share intent by again calling + * mShareActionProvider.{@link android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} + */ +private Intent getDefaultIntent() { + Intent intent = new Intent(Intent.ACTION_SEND); + intent.setType("image/*"); + return intent; } -// When you need to update the share intent somewhere else in the app, call -// mShareActionProvider.{@link android.widget.ShareActionProvider#setShareIntent setShareIntent()} </pre> -<p>The {@link android.widget.ShareActionProvider} now handles all user interaction with the item and -you <em>do not</em> need to handle click events from the {@link +<p>The {@link android.support.v7.widget.ShareActionProvider} now handles all user interaction with +the item and you <em>do not</em> need to handle click events from the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p> -<p>For a sample using the share action provider, see -<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarShareActionProviderActivity.html" ->ActionBarShareActionProviderActivity</a>. + +<p>By default, the {@link android.support.v7.widget.ShareActionProvider} retains a ranking for each +share target based on how often the user selects each one. The share targets used more frequently +appear at the top of the drop-down list and the target used most often appears directly in the +action bar as the default share target. By default, the ranking information is saved in a private +file with a name specified by {@link +android.support.v7.widget.ShareActionProvider#DEFAULT_SHARE_HISTORY_FILE_NAME}. If you use the +{@link android.support.v7.widget.ShareActionProvider} or an extension of it for only one type of +action, then you should continue to use this default history file and there's nothing you need to +do. However, if you use {@link android.support.v7.widget.ShareActionProvider} or an extension of it +for multiple actions with semantically different meanings, then each {@link +android.support.v7.widget.ShareActionProvider} should specify its own history file in order to +maintain its own history. To specify a different history file for the {@link +android.support.v7.widget.ShareActionProvider}, call {@link +android.support.v7.widget.ShareActionProvider#setShareHistoryFileName setShareHistoryFileName()} +and provide an XML file name (for example, {@code "custom_share_history.xml"}).</p> + + +<p class="note"><strong>Note:</strong> Although the {@link +android.support.v7.widget.ShareActionProvider} ranks share targets based on frequency of use, the +behavior is extensible and extensions of {@link android.support.v7.widget.ShareActionProvider} can +perform different behaviors and ranking based on the history file (if appropriate).</p> + <h3 id="CreatingActionProvider">Creating a custom action provider</h3> -<p>When you want to create an action view that has dynamic behaviors and a default action in the -overflow menu, extending {@link android.view.ActionProvider} to define those behaviors is a good -solution. Creating your own action provider offers you an organized and reusable component, rather -than handling the various action item transformations and behaviors in your fragment or activity -code. As shown in the previous section, Android provides one implementation of {@link -android.view.ActionProvider} for share actions: the {@link android.widget.ShareActionProvider}.</p> +<p>Creating your own action provider allows you to re-use and manage dynamic action item +behaviors in a self-contained module, rather than handle action item transformations and +behaviors in your fragment or activity +code. As shown in the previous section, Android already provides an implementation of {@link +android.support.v4.view.ActionProvider} for share actions: the {@link +android.support.v7.widget.ShareActionProvider}.</p> -<p>To create your own, simply extend the {@link android.view.ActionProvider} class and implement +<p>To create your own action provider for a different action, simply extend the +{@link android.support.v4.view.ActionProvider} class and implement its callback methods as appropriate. Most importantly, you should implement the following:</p> <dl> - <dt>{@link android.view.ActionProvider#ActionProvider ActionProvider()}</dt> + <dt>{@link android.support.v4.view.ActionProvider#ActionProvider ActionProvider()}</dt> <dd>This constructor passes you the application {@link android.content.Context}, which you should save in a member field to use in the other callback methods.</dd> - <dt>{@link android.view.ActionProvider#onCreateActionView()}</dt> + <dt>{@link android.support.v4.view.ActionProvider#onCreateActionView(MenuItem)}</dt> <dd>This is where you define the action view for the item. Use the {@link android.content.Context} acquired from the constructor to instantiate a {@link android.view.LayoutInflater} and inflate your action view layout from an XML resource, then hook up event listeners. For example: <pre> -public View onCreateActionView() { +public View onCreateActionView(MenuItem forItem) { // Inflate the action view to be shown on the action bar. LayoutInflater layoutInflater = LayoutInflater.from(mContext); View view = layoutInflater.inflate(R.layout.action_provider, null); @@ -903,18 +851,21 @@ public View onCreateActionView() { </pre> </dd> - <dt>{@link android.view.ActionProvider#onPerformDefaultAction()}</dt> - <dd>The system calls this when the menu item is selected from the overflow menu and the + <dt>{@link android.support.v4.view.ActionProvider#onPerformDefaultAction()}</dt> + <dd>The system calls this when the menu item is selected from the action overflow and the action provider should perform a default action for the menu item. <p>However, if your action provider provides a submenu, through the {@link -android.view.ActionProvider#onPrepareSubMenu onPrepareSubMenu()} callback, then the submenu -appears even when the menu item is in the overflow menu. Thus, {@link -android.view.ActionProvider#onPerformDefaultAction()} is never called when there is a +android.support.v4.view.ActionProvider#onPrepareSubMenu onPrepareSubMenu()} callback, then the +submenu appears even when the action provider is placed in the action overflow. Thus, {@link +android.support.v4.view.ActionProvider#onPerformDefaultAction()} is never called when there is a submenu.</p> + <p class="note"><strong>Note:</strong> An activity or a fragment that implements {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} can override the action -provider's default behavior by handling the item-selected event (and returning true), in which -case, the system does not call {@link android.view.ActionProvider#onPerformDefaultAction()}.</p> +provider's default behavior (unless it uses a submenu) by handling the item-selected event (and +returning <code>true</code>), in which case, the system does not call {@link +android.support.v4.view.ActionProvider#onPerformDefaultAction()}.</p> + </dd> </dl> @@ -927,62 +878,68 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/Acti <h2 id="Tabs">Adding Navigation Tabs</h2> +<img src="{@docRoot}images/ui/actionbar-tabs@2x.png" width="760" alt="" /> +<p class="img-caption"><strong>Figure 7.</strong> Action bar tabs on a wide screen.</p> -<div class="figure" style="width:450px"> - <img src="{@docRoot}images/ui/actionbar.png" alt="" /> - <p class="img-caption"><strong>Figure 9.</strong> Screenshot of action bar tabs from the <a -href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app.</p> -</div> +<a class="notice-designers" href="{@docRoot}design/building-blocks/tabs.html"> + <div> + <h3>Design Guide</h3> + <p>Tabs</p> + </div> +</a> + +<a class="notice-developers" href="{@docRoot}training/implementing-navigation/lateral.html"> + <div> + <h3>Also read</h3> + <p>Creating Swipe Views with Tabs</p> + </div> +</a> -<div class="figure" style="width:250px"> - <img src="{@docRoot}images/ui/actionbar-stacked.png" alt="" /> - <p class="img-caption"><strong>Figure 10.</strong> Screenshot of tabs in the stacked action -bar on a narrow screen.</p> + +<div class="figure" style="width:240px"> + <img src="{@docRoot}images/ui/actionbar-tabs-stacked@2x.png" width="240" alt="" /> + <p class="img-caption"><strong>Figure 8.</strong> Tabs on a narrow screen.</p> </div> -<p>When you want to provide navigation tabs in an activity, using the action bar's -tabs is a great option (instead of using {@link android.widget.TabWidget}), because the -system adapts the action bar tabs for different screen sizes—placing them in the main action -bar when the screen is sufficiently wide, or in a separate bar (known as the "stacked action bar") -when the screen is too narrow, as shown in figures 9 and 10.</p> - -<p>To switch between fragments using the tabs, you must perform a fragment -transaction each time a tab is selected. If you're not familiar with how to change fragments -using {@link android.app.FragmentTransaction}, first read the <a -href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.</p> - -<p>To get started, your layout must include a {@link android.view.ViewGroup} in which you place each -{@link android.app.Fragment} associated with a tab. Be sure the {@link android.view.ViewGroup} has a -resource ID so you can reference it from your tab-swapping code. Alternatively, if the tab content -will fill the activity layout (excluding the action bar), then your activity doesn't need a layout -at all (you don't even need to call {@link android.app.Activity#setContentView -setContentView()}). Instead, you can place each fragment in the default root {@link -android.view.ViewGroup}, which you can refer to with the {@code android.R.id.content} ID (you can -see this ID used in the sample code below, during fragment transactions).</p> +<p>Tabs in the action bar make it easy for users to explore and switch between different views in +your app. The tabs provided by the {@link android.support.v7.app.ActionBar} are ideal because they +adapt to different screen sizes. For example, when the screen is wide enough the tabs appear in the +action bar alongside the action buttons (such as when on a tablet, shown in figure 7), while when +on a narrow screen they appear in a separate bar (known as the "stacked action bar", shown in +figure 8). In some cases, the Android system will instead show your tab items as a drop-down list +to ensure the best fit in the action bar.</p> + +<p>To get started, your layout must include a {@link android.view.ViewGroup} in which you place +each {@link android.app.Fragment} associated with a tab. Be sure the {@link android.view.ViewGroup} +has a resource ID so you can reference it from your code and swap the tabs within it. +Alternatively, if the tab content will fill the activity layout, then your activity doesn't need a +layout at all (you don't even need to call {@link android.app.Activity#setContentView +setContentView()}). Instead, you can place each fragment in the default root view, which you can +refer to with the {@code android.R.id.content} ID.</p> + <p>Once you determine where the fragments appear in the layout, the basic procedure to add tabs is:</p> <ol> - <li>Implement the {@link android.app.ActionBar.TabListener} interface. Callbacks in this -interface respond to user events on the tabs so you can swap fragments.</li> - <li>For each tab you want to add, instantiate an {@link android.app.ActionBar.Tab} and set the -{@link android.app.ActionBar.TabListener} by calling {@link android.app.ActionBar.Tab#setTabListener -setTabListener()}. Also set the tab's title and/or icon with {@link -android.app.ActionBar.Tab#setText setText()} and/or {@link android.app.ActionBar.Tab#setIcon -setIcon()}.</li> - <li>Add each tab to the action bar by calling {@link android.app.ActionBar#addTab addTab()}.</li> + <li>Implement the {@link android.support.v7.app.ActionBar.TabListener} interface. This interface + provides callbacks for tab events, such as when the user presses one so you can swap the + tabs.</li> + <li>For each tab you want to add, instantiate an {@link android.support.v7.app.ActionBar.Tab} + and set the {@link android.support.v7.app.ActionBar.TabListener} by calling {@link + android.support.v7.app.ActionBar.Tab#setTabListener setTabListener()}. Also set the tab's title + and with {@link android.app.ActionBar.Tab#setText setText()} (and optionally, an icon with + {@link android.app.ActionBar.Tab#setIcon setIcon()}).</li> + <li>Then add each tab to the action bar by calling {@link android.support.v7.app.ActionBar#addTab + addTab()}.</li> </ol> -<p>When looking at the {@link android.app.ActionBar.TabListener} interface, notice that the -callback methods provide only the {@link android.app.ActionBar.Tab} that was selected and a {@link -android.app.FragmentTransaction} for you to perform fragment transactions—it doesn't say -anything about what fragment you should swap in or out. Thus, you must define your own association +<p>Notice that the {@link android.support.v7.app.ActionBar.TabListener} +callback methods don't specify which fragment is associated with the tab, but merely which +{@link android.support.v7.app.ActionBar.Tab} was selected. +You must define your own association between each {@link android.app.ActionBar.Tab} and the appropriate {@link android.app.Fragment} that -it represents (in order to perform the appropriate fragment transaction). There are several ways you -can define the association, depending on your design. In the example below, the {@link -android.app.ActionBar.TabListener} implementation provides a constructor such that each new tab uses -its own instance of the listener. Each instance of the listener defines several fields that are -necessary to later perform a transaction on the appropriate fragment.</p> +it represents. There are several ways you +can define the association, depending on your design.</p> <p>For example, here's how you might implement the {@link android.app.ActionBar.TabListener} such that each tab uses its own instance of the listener:</p> @@ -1042,13 +999,10 @@ adds ({@link android.app.FragmentTransaction#add add()}) it to the layout (as a android.R.id.content} view group)—when the respective tab is selected, and detaches ({@link android.app.FragmentTransaction#detach detach()}) it when the tab is unselected.</p> -<p>The {@link android.app.ActionBar.TabListener} implementation is the bulk of the work. All that -remains is to create each {@link android.app.ActionBar.Tab} and add it to the {@link +<p>All that remains is to create each {@link android.app.ActionBar.Tab} and add it to the {@link android.app.ActionBar}. Additionally, you must call {@link android.app.ActionBar#setNavigationMode(int) setNavigationMode(NAVIGATION_MODE_TABS)} to make the -tabs visible. You might also want to disable the activity title by calling {@link -android.app.ActionBar#setDisplayShowTitleEnabled setDisplayShowTitleEnabled(false)} if the tab -titles actually indicate the current view.</p> +tabs visible.</p> <p>For example, the following code adds two tabs using the listener defined above:</p> @@ -1060,62 +1014,70 @@ protected void onCreate(Bundle savedInstanceState) { // android.R.id.content as the container for each fragment // setup action bar for tabs - ActionBar actionBar = getActionBar(); + ActionBar actionBar = getSupportActionBar(); actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); actionBar.setDisplayShowTitleEnabled(false); Tab tab = actionBar.newTab() - .setText(R.string.artist) - .setTabListener(new TabListener<ArtistFragment>( - this, "artist", ArtistFragment.class)); + .setText(R.string.artist) + .setTabListener(new TabListener<ArtistFragment>( + this, "artist", ArtistFragment.class)); actionBar.addTab(tab); tab = actionBar.newTab() - .setText(R.string.album) - .setTabListener(new TabListener<AlbumFragment>( - this, "album", AlbumFragment.class)); + .setText(R.string.album) + .setTabListener(new TabListener<AlbumFragment>( + this, "album", AlbumFragment.class)); actionBar.addTab(tab); } </pre> -<p class="note"><strong>Note:</strong> The above implementation for {@link -android.app.ActionBar.TabListener} is one of several possible techniques. You can see more of -this style in the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentTabs.html" ->API Demos</a> app.</p> +<p>If your activity stops, you should retain the currently selected tab with the <a href= +"{@docRoot}guide/components/activities.html#SavingActivityState">saved instance state</a> so you +can open the appropriate tab when the user returns. When it's time to save the state, you can query +the currently selected tab with {@link +android.support.v7.app.ActionBar#getSelectedNavigationIndex()}. This returns the index position of +the selected tab.</p> -<p>If your activity stops, you should retain the currently selected tab with the <a -href="{@docRoot}guide/components/activities.html#SavingActivityState">saved instance -state</a> so you can open the appropriate tab when the user returns. When it's time to save the -state, you can query the currently selected tab with {@link -android.app.ActionBar#getSelectedNavigationIndex()}. This returns the index position of the selected -tab.</p> <p class="caution"><strong>Caution:</strong> It's important that you save the state of each fragment -as necessary, so that when users switch fragments with the tabs and then return to a previous -fragment, it looks the way it did when they left. For information about saving the state of your +so when users switch fragments with the tabs and then return to a previous +fragment, it looks the way it did when they left. Some of the state is saved by default, but you +may need to manually save state for customized views. For information about saving the state of your fragment, see the <a href="{@docRoot}guide/components/fragments.html">Fragments</a> -developer guide.</p> +API guide.</p> + +<p class="note"><strong>Note:</strong> The above implementation for {@link +android.support.v7.app.ActionBar.TabListener} is one of several possible techniques. Another popular +option is to use {@link android.support.v4.view.ViewPager} to manage the fragments so users +can also use a swipe gesture to switch tabs. In this case, you simply tell the +{@link android.support.v4.view.ViewPager} the current tab position in the +{@link android.support.v7.app.ActionBar.TabListener#onTabSelected onTabSelected()} callback. +For more information, read +<a href="{@docRoot}training/implementing-navigation/lateral.html" +>Creating Swipe Views with Tabs</a>.</p> -<p class="note"><strong>Note:</strong> In some cases, the Android system will show your action -bar tabs as a drop-down list in order to ensure the best fit in the action bar.</p> -<h2 id="Dropdown">Adding Drop-down Navigation</h2> -<p>As another mode of navigation (or filtering) within your activity, the action bar offers a -built in drop-down list. For example, the drop-down list can offer different modes by which content -in the activity is sorted.</p> +<h2 id="Dropdown">Adding Drop-down Navigation</h2> -<!-- -<div class="figure" style="width:135px"> - <img src="{@docRoot}images/ui/actionbar-dropdown.png" alt="" /> - <p class="img-caption"><strong>Figure 5.</strong> Screenshot of a drop-down navigation list in the +<div class="figure" style="width:240px"> + <img src="{@docRoot}images/ui/actionbar-dropdown@2x.png" alt="" width="240" /> + <p class="img-caption"><strong>Figure 9.</strong> A drop-down navigation list in the action bar.</p> </div> ---> + +<p>As another mode of navigation (or filtering) for your activity, the action bar offers a built +in drop-down list (also known as a "spinner"). For example, the drop-down list can offer different +modes by which content in the activity is sorted.</p> + +<p>Using the drop-down list is useful when changing the content is important but not necessarily a +frequent occurrence. In cases where switching the content is more frequent, +you should use <a href="#Tabs">navigation tabs</a> instead.</p> + <p>The basic procedure to enable drop-down navigation is:</p> @@ -1123,36 +1085,31 @@ action bar.</p> <li>Create a {@link android.widget.SpinnerAdapter} that provides the list of selectable items for the drop-down and the layout to use when drawing each item in the list.</li> - <li>Implement {@link android.app.ActionBar.OnNavigationListener} to define the behavior that -occurs when the user selects an item from the list.</li> - <li>Enable navigation mode for the action bar with {@link -android.app.ActionBar#setNavigationMode setNavigationMode()}. For example: -<pre> -ActionBar actionBar = getActionBar(); -actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST); -</pre> - <p class="note"><strong>Note:</strong> You should perform this during your activity's {@link -android.app.Activity#onCreate -onCreate()} method.</p> + <li>Implement {@link android.support.v7.app.ActionBar.OnNavigationListener} to define the + behavior that occurs when the user selects an item from the list.</li> + <li>During your activity's {@link android.app.Activity#onCreate +onCreate()} method, enable the action bar's drop-down list by calling {@link +android.support.v7.app.ActionBar#setNavigationMode setNavigationMode(NAVIGATION_MODE_LIST)}. </li> <li>Set the callback for the drop-down list with {@link -android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}. For example: +android.support.v7.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}. +For example: <pre> actionBar.setListNavigationCallbacks(mSpinnerAdapter, mNavigationCallback); </pre> <p>This method takes your {@link android.widget.SpinnerAdapter} and {@link -android.app.ActionBar.OnNavigationListener}.</p> +android.support.v7.app.ActionBar.OnNavigationListener}.</p> </li> </ol> -<p>That's the basic setup. However, implementing the {@link android.widget.SpinnerAdapter} and -{@link android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are many -ways you can implement these to define the functionality for your drop-down navigation and +<p>This procedure is relatively short, but implementing the {@link android.widget.SpinnerAdapter} +and {@link android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are +many ways you can implement these to define the functionality for your drop-down navigation and implementing various types of {@link android.widget.SpinnerAdapter} is beyond the scope of this document (you should refer to the {@link android.widget.SpinnerAdapter} class reference for more -information). However, below is a simple example for a {@link android.widget.SpinnerAdapter} and -{@link android.app.ActionBar.OnNavigationListener} to get you started (click the title to -reveal the sample).</p> +information). However, below is an example for a {@link android.widget.SpinnerAdapter} and {@link +android.app.ActionBar.OnNavigationListener} to get you started (click the title to reveal the +sample).</p> @@ -1283,31 +1240,71 @@ public class ListContentFragment extends Fragment { -<h2 id="Style">Styling the Action Bar</h2> -<p>If you've implemented a custom design for the widgets in your application, you might -also want to redesign some of the action bar to match your app design. To do so, you need to use -Android's <a -href="{@docRoot}guide/topics/ui/themes.html">style and theme</a> framework to restyle the action -bar using special style properties.</p> +<h2 id="Style">Styling the Action Bar</h2> + +<p>If you want to implement a visual design that represents your app's brand, the action bar allows +you to customize each detail of its appearance, including the action bar color, text colors, button +styles, and more. To do so, you need to use Android's <a href= +"{@docRoot}guide/topics/ui/themes.html">style and theme</a> framework to restyle the action bar +using special style properties.</p> -<p class="note"><strong>Note:</strong> In order for background images to change appearance -depending on the current button state (selected, pressed, unselected), the drawable resource you use -must be a <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state -list drawable</a>.</p> +<p class="caution"><strong>Caution:</strong> For all background drawables you provide, be sure to +use <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch drawables</a> +to allow stretching. The nine-patch image should be <em>smaller</em> than 40dp tall and 30dp +wide.</p> -<p class="caution"><strong>Caution:</strong> For all background drawables you provide, be sure to use <a -href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch drawables</a> to allow -stretching. The Nine-Patch image should be <em>smaller</em> than 40px tall and 30px wide (for the mdpi asset).</p> <h3 id="GeneralStyles">General appearance</h3> <dl> + <dt>{@link android.R.attr#actionBarStyle + actionBarStyle}</dt> + <dd>Specifies a style resource that defines various style properties + for the action bar. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar + Widget.AppCompat.ActionBar}, which is what you should use as the parent style.</p> + <p>Supported styles include:</p> + <dl> + <dt>{@link android.R.attr#background}</dt> + <dd>Defines a drawable resource for the action bar background.</dd> + <dt>{@link android.R.attr#backgroundStacked}</dt> + <dd>Defines a drawable resource for the stacked action bar + (the <a href="#Tabs">tabs</a>).</dd> + <dt>{@link android.R.attr#backgroundSplit}</dt> + <dd>Defines a drawable resource for the <a href="#SplitBar">split action bar</a>.</dd> + <dt>{@link android.R.attr#actionButtonStyle}</dt> + <dd>Defines a style resource for action buttons. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionButton + Widget.AppCompat.ActionButton}, which is what you should use as the parent style.</p> + </dd> + <dt>{@link android.R.attr#actionOverflowButtonStyle}</dt> + <dd>Defines a style resource for overflow action items. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionButton_Overflow + Widget.AppCompat.ActionButton.Overflow}, which is what you should use as the parent style.</p> + </dd> + <dt>{@link android.R.attr#displayOptions}</dt> + <dd>Defines one or more action bar display options, such as whether to use the app logo, + show the activity title, or enable the <em>Up</em> action. See {@link + android.R.attr#displayOptions} for all possible values. + <dt>{@link android.R.attr#divider}</dt> + <dd>Defines a drawable resource for the divider between action items.</dd> + <dt>{@link android.R.attr#titleTextStyle}</dt> + <dd>Defines a style resource for the action bar title. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#TextAppearance_AppCompat_Widget_ActionBar_Title + TextAppearance.AppCompat.Widget.ActionBar.Title}, which is what you should use as the parent + style.</p></dd> + </dl> + </dd> <dt>{@link android.R.attr#windowActionBarOverlay - android:windowActionBarOverlay}</dt> + windowActionBarOverlay}</dt> <dd>Declares whether the action bar should overlay the activity layout rather than offset the activity's layout position (for example, the Gallery app uses overlay mode). This is {@code false} by default. @@ -1322,9 +1319,9 @@ bar.</p> draw the action bar with a semi-transparent background by default. However, you can modify it with your own styles and the {@link android.R.style#Theme_DeviceDefault DeviceDefault} theme on different devices might use an opaque background by default.</p> - <p>When overlay mode is enabled, your activity layout has no awareness of the action bar laying on + <p>When overlay mode is enabled, your activity layout has no awareness of the action bar lying on top of it. So, you must be careful not to place any important information or UI components in the -area overlayed by the action bar. If appropriate, you can refer to the platform's value for {@link +area overlaid by the action bar. If appropriate, you can refer to the platform's value for {@link android.R.attr#actionBarSize} to determine the height of the action bar, by referencing it in your XML layout. For example:</p> <pre> @@ -1334,13 +1331,13 @@ in your XML layout. For example:</p> </pre> <p>You can also retrieve the action bar height at runtime with {@link android.app.ActionBar#getHeight()}. This reflects the height of the action bar at the time it's -called, which might not include the stacked action bar (due to navigation tabs) if called during early -activity lifecycle methods. To see how you can determine the total height at runtime, including the -stacked action bar, see the <a -href="{@docRoot}resources/samples/HoneycombGallery/src/com/example/android/hcgallery/TitlesFragment.html" ->{@code TitlesFragment}</a> class in the <a -href="{@docRoot}resources/samples/HoneycombGallery/index.html" ->Honeycomb Gallery</a> sample app.</p> +called, which might not include the stacked action bar (due to navigation tabs) if called during +early activity lifecycle methods. To see how you can determine the total height at runtime, +including the stacked action bar, see the <a href= +"{@docRoot}resources/samples/HoneycombGallery/src/com/example/android/hcgallery/TitlesFragment.html"> +{@code TitlesFragment}</a> class in the <a href= +"{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> sample app.</p> + </dd> </dl> @@ -1350,34 +1347,40 @@ href="{@docRoot}resources/samples/HoneycombGallery/index.html" <dl> <dt>{@link android.R.attr#actionButtonStyle - android:actionButtonStyle}</dt> - <dd>Defines a style resource for the action item buttons.</dd> + actionButtonStyle}</dt> + <dd>Defines a style resource for the action item buttons. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionButton + Widget.AppCompat.ActionButton}, which is what you should use as the parent style.</p></dd> <dt>{@link android.R.attr#actionBarItemBackground - android:actionBarItemBackground}</dt> - <dd>Defines a drawable resource for each action item's background. (Added in API level 14.)</dd> + actionBarItemBackground}</dt> + <dd>Defines a drawable resource for each action item's background. + This should be a <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList" + >state-list drawable</a> to indicate different selected states.</dd> <dt>{@link android.R.attr#itemBackground - android:itemBackground}</dt> - <dd>Defines a drawable resource for each overflow menu item's background.</dd> + itemBackground}</dt> + <dd>Defines a drawable resource for each action overflow item's background. + This should be a <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList" + >state-list drawable</a> to indicate different selected states.</dd> <dt>{@link android.R.attr#actionBarDivider - android:actionBarDivider}</dt> - <dd>Defines a drawable resource for the divider between action items. (Added in API level -14.)</dd> + actionBarDivider}</dt> + <dd>Defines a drawable resource for the divider between action items.</dd> <dt>{@link android.R.attr#actionMenuTextColor - android:actionMenuTextColor}</dt> + actionMenuTextColor}</dt> <dd>Defines a color for text that appears in an action item.</dd> <dt>{@link android.R.attr#actionMenuTextAppearance - android:actionMenuTextAppearance}</dt> + actionMenuTextAppearance}</dt> <dd>Defines a style resource for text that appears in an action item.</dd> <dt>{@link android.R.attr#actionBarWidgetTheme - android:actionBarWidgetTheme}</dt> + actionBarWidgetTheme}</dt> <dd>Defines a theme resource for widgets that are inflated into the action bar as <a -href="#ActionView">action views</a>. (Added in API level 14.)</dd> +href="#ActionView">action views</a>.</dd> </dl> @@ -1385,16 +1388,25 @@ href="#ActionView">action views</a>. (Added in API level 14.)</dd> <dl> <dt>{@link android.R.attr#actionBarTabStyle - android:actionBarTabStyle}</dt> - <dd>Defines a style resource for tabs in the action bar.</dd> + actionBarTabStyle}</dt> + <dd>Defines a style resource for tabs in the action bar. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar_TabView + Widget.AppCompat.ActionBar.TabView}, which is what you should use as the parent style.</p></dd> <dt>{@link android.R.attr#actionBarTabBarStyle - android:actionBarTabBarStyle}</dt> - <dd>Defines a style resource for the thin bar that appears below the navigation tabs.</dd> + actionBarTabBarStyle}</dt> + <dd>Defines a style resource for the thin bar that appears below the navigation tabs. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar_TabBar + Widget.AppCompat.ActionBar.TabBar}, which is what you should use as the parent style.</p></dd> <dt>{@link android.R.attr#actionBarTabTextStyle - android:actionBarTabTextStyle}</dt> - <dd>Defines a style resource for text in the navigation tabs.</dd> + actionBarTabTextStyle}</dt> + <dd>Defines a style resource for text in the navigation tabs. + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar_TabText + Widget.AppCompat.ActionBar.TabText}, which is what you should use as the parent style.</p></dd> </dl> @@ -1402,82 +1414,93 @@ href="#ActionView">action views</a>. (Added in API level 14.)</dd> <dl> <dt>{@link android.R.attr#actionDropDownStyle - android:actionDropDownStyle}</dt> - <dd>Defines a style for the drop-down navigation (such as the background and text styles).</dd> + actionDropDownStyle}</dt> + <dd>Defines a style for the drop-down navigation (such as the background and text styles). + <p>The default for this style for this + is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_Spinner_DropDown_ActionBar + Widget.AppCompat.Spinner.DropDown.ActionBar}, which is what you should use as the parent + style.</p></dd> </dl> +<h3 id="StyleExample">Example theme</h3> + +<p>Here's an example that defines a custom theme for an activity, {@code CustomActivityTheme}, +that includes several styles to customize the action bar.</p> -<p>For example, here's a file that defines a few custom styles for the action bar:</p> +<p>Notice that there are two version for each action bar style property. The first one +includes the {@code android:} prefix on the property name to support API levels 11 and higher +that include these properties in the framework. The second version does <em>not</em> +include the {@code android:} prefix and is for older versions of the platform, on which +the system uses the style property from the support library. The effect for each is the same.</p> <pre> <?xml version="1.0" encoding="utf-8"?> <resources> <!-- the theme applied to the application or activity --> - <style name="CustomActivityTheme" parent="@android:style/Theme.Holo"> - <item name="android:actionBarTabTextStyle">@style/CustomTabTextStyle</item> - <item name="android:actionBarDivider">@drawable/ab_divider</item> - <item name="android:actionBarItemBackground">@drawable/ab_item_background</item> + <style name="CustomActionBarTheme" + parent="@style/Theme.AppCompat.Light"> + <item name="android:actionBarStyle">@style/MyActionBar</item> + <item name="android:actionBarTabTextStyle">@style/TabTextStyle</item> + <item name="android:actionMenuTextColor">@color/actionbar_text</item> + + <!-- Support library compatibility --> + <item name="actionBarStyle">@style/MyActionBar</item> + <item name="actionBarTabTextStyle">@style/TabTextStyle</item> + <item name="actionMenuTextColor">@color/actionbar_text</item> </style> - <!-- style for the action bar tab text --> - <style name="CustomTabTextStyle" parent="@android:style/TextAppearance.Holo"> - <item name="android:textColor">#2456c2</item> + <!-- general styles for the action bar --> + <style name="MyActionBar" + parent="@style/Widget.AppCompat.ActionBar"> + <item name="android:titleTextStyle">@style/TitleTextStyle</item> + <item name="android:background">@drawable/actionbar_background</item> + <item name="android:backgroundStacked">@drawable/actionbar_background</item> + <item name="android:backgroundSplit">@drawable/actionbar_background</item> + + <!-- Support library compatibility --> + <item name="titleTextStyle">@style/TitleTextStyle</item> + <item name="background">@drawable/actionbar_background</item> + <item name="backgroundStacked">@drawable/actionbar_background</item> + <item name="backgroundSplit">@drawable/actionbar_background</item> </style> -</resources> -</pre> -<p class="note"><strong>Note:</strong> Be certain that your theme declares a parent theme in the -{@code <style>} tag, from which it inherits all styles not explicitly declared by your theme. -When modifying the action bar, using a parent theme is important so that you can simply override the -action bar styles you want to change without re-implementing the styles you want to leave alone -(such as text appearance or padding in action items).</p> + <!-- action bar title text --> + <style name="TitleTextStyle" + parent="@style/TextAppearance.AppCompat.Widget.ActionBar.Title"> + <item name="android:textColor">@color/actionbar_text</item> + </style> -<p>You can apply your custom theme to the entire application or to individual activities in your -manifest file like this:</p> + <!-- action bar tab text --> + <style name="TabTextStyle" + parent="@style/Widget.AppCompat.ActionBar.TabText"> + <item name="android:textColor">@color/actionbar_text</item> + </style> +</resources> -<pre> -<application android:theme="@style/CustomActivityTheme" ... /> </pre> -<p>For more information about using style and theme resources in your application, read <a -href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> - - -<h3 id="AdvancedStyles">Advanced styling</h3> +<p>In your manifest file, you can apply the theme to your entire app:</p> - <p>If you need more advanced styling for the action bar than is available with the -properties above, you can include {@link android.R.attr#actionBarStyle android:actionBarStyle} and -{@link android.R.attr#actionBarSplitStyle android:actionBarSplitStyle} in your activity's theme. -Each of these specifies another style that can define various properties for the action bar, -including different backgrounds with {@link android.R.attr#background android:background}, {@link -android.R.attr#backgroundSplit android:backgroundSplit}, and {@link android.R.attr#backgroundStacked -android:backgroundStacked}. If you override these action bar styles, be sure that you define a -parent action bar style such as {@link android.R.style#Widget_Holo_ActionBar -Widget.Holo.ActionBar}.</p> +<pre> +<application android:theme="@style/CustomActionBarTheme" ... /> +</pre> -<p>For example, if you want to change the action bar's background, you can use the following -styles:</p> +<p>Or to individual activities:</p> <pre> -<?xml version="1.0" encoding="utf-8"?> -<resources> - <!-- the theme applied to the application or activity --> - <style name="CustomActivityTheme" parent="@android:style/Theme.Holo"> - <item name="android:actionBarStyle">@style/MyActionBar</item> - <!-- other activity and action bar styles here --> - </style> - - <!-- style for the action bar backgrounds --> - <style name="MyActionBar" parent="@android:style/Widget.Holo.ActionBar"> - <item name="android:background">@drawable/ab_background</item> - <item name="android:backgroundStacked">@drawable/ab_background</item> - <item name="android:backgroundSplit">@drawable/ab_split_background</item> - </style> -</resources> +<activity android:theme="@style/CustomActionBarTheme" ... /> </pre> +<p class="caution"><strong>Caution:</strong> Be certain that each theme and style declares a parent +theme in the {@code <style>} tag, from which it inherits all styles not explicitly declared +by your theme. When modifying the action bar, using a parent theme is important so that you can +simply override the action bar styles you want to change without re-implementing the styles you +want to leave alone (such as text size or padding in action items).</p> + +<p>For more information about using style and theme resources in your application, read <a +href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> |