ActivityCompat.java revision a52784195525cdb1f2bb4d8dde1b8b314f480957
1/* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.support.v4.app; 18 19import android.app.Activity; 20import android.content.Context; 21import android.content.Intent; 22import android.graphics.Matrix; 23import android.graphics.RectF; 24import android.os.Build; 25import android.os.Bundle; 26import android.os.Parcelable; 27import android.support.annotation.Nullable; 28import android.support.v4.content.ContextCompat; 29import android.view.View; 30 31import java.util.List; 32import java.util.Map; 33 34/** 35 * Helper for accessing features in {@link android.app.Activity} 36 * introduced after API level 4 in a backwards compatible fashion. 37 */ 38public class ActivityCompat extends ContextCompat { 39 /** 40 * Invalidate the activity's options menu, if able. 41 * 42 * <p>Before API level 11 (Android 3.0/Honeycomb) the lifecycle of the 43 * options menu was controlled primarily by the user's operation of 44 * the hardware menu key. When the user presses down on the menu key 45 * for the first time the menu was created and prepared by calls 46 * to {@link Activity#onCreateOptionsMenu(android.view.Menu)} and 47 * {@link Activity#onPrepareOptionsMenu(android.view.Menu)} respectively. 48 * Subsequent presses of the menu key kept the existing instance of the 49 * Menu itself and called {@link Activity#onPrepareOptionsMenu(android.view.Menu)} 50 * to give the activity an opportunity to contextually alter the menu 51 * before the menu panel was shown.</p> 52 * 53 * <p>In Android 3.0+ the Action Bar forces the options menu to be built early 54 * so that items chosen to show as actions may be displayed when the activity 55 * first becomes visible. The Activity method invalidateOptionsMenu forces 56 * the entire menu to be destroyed and recreated from 57 * {@link Activity#onCreateOptionsMenu(android.view.Menu)}, offering a similar 58 * though heavier-weight opportunity to change the menu's contents. Normally 59 * this functionality is used to support a changing configuration of Fragments.</p> 60 * 61 * <p>Applications may use this support helper to signal a significant change in 62 * activity state that should cause the options menu to be rebuilt. If the app 63 * is running on an older platform version that does not support menu invalidation 64 * the app will still receive {@link Activity#onPrepareOptionsMenu(android.view.Menu)} 65 * the next time the user presses the menu key and this method will return false. 66 * If this method returns true the options menu was successfully invalidated.</p> 67 * 68 * @param activity Invalidate the options menu of this activity 69 * @return true if this operation was supported and it completed; false if it was not available. 70 */ 71 public static boolean invalidateOptionsMenu(Activity activity) { 72 if (Build.VERSION.SDK_INT >= 11) { 73 ActivityCompatHoneycomb.invalidateOptionsMenu(activity); 74 return true; 75 } 76 return false; 77 } 78 79 /** 80 * Start an activity with additional launch information, if able. 81 * 82 * <p>In Android 4.1+ additional options were introduced to allow for more 83 * control on activity launch animations. Applications can use this method 84 * along with {@link ActivityOptionsCompat} to use these animations when 85 * available. When run on versions of the platform where this feature does 86 * not exist the activity will be launched normally.</p> 87 * 88 * @param activity Context to launch activity from. 89 * @param intent The description of the activity to start. 90 * @param options Additional options for how the Activity should be started. 91 * May be null if there are no options. See 92 * {@link ActivityOptionsCompat} for how to build the Bundle 93 * supplied here; there are no supported definitions for 94 * building it manually. 95 */ 96 public static void startActivity(Activity activity, Intent intent, @Nullable Bundle options) { 97 if (Build.VERSION.SDK_INT >= 16) { 98 ActivityCompatJB.startActivity(activity, intent, options); 99 } else { 100 activity.startActivity(intent); 101 } 102 } 103 104 /** 105 * Start new activity with options, if able, for which you would like a 106 * result when it finished. 107 * 108 * <p>In Android 4.1+ additional options were introduced to allow for more 109 * control on activity launch animations. Applications can use this method 110 * along with {@link ActivityOptionsCompat} to use these animations when 111 * available. When run on versions of the platform where this feature does 112 * not exist the activity will be launched normally.</p> 113 * 114 * @param activity Origin activity to launch from. 115 * @param intent The description of the activity to start. 116 * @param requestCode If >= 0, this code will be returned in 117 * onActivityResult() when the activity exits. 118 * @param options Additional options for how the Activity should be started. 119 * May be null if there are no options. See 120 * {@link ActivityOptionsCompat} for how to build the Bundle 121 * supplied here; there are no supported definitions for 122 * building it manually. 123 */ 124 public static void startActivityForResult(Activity activity, Intent intent, int requestCode, 125 @Nullable Bundle options) { 126 if (Build.VERSION.SDK_INT >= 16) { 127 ActivityCompatJB.startActivityForResult(activity, intent, requestCode, options); 128 } else { 129 activity.startActivityForResult(intent, requestCode); 130 } 131 } 132 133 /** 134 * Finish this activity, and tries to finish all activities immediately below it 135 * in the current task that have the same affinity. 136 * 137 * <p>On Android 4.1+ calling this method will call through to the native version of this 138 * method. For other platforms {@link Activity#finish()} will be called instead.</p> 139 */ 140 public static void finishAffinity(Activity activity) { 141 if (Build.VERSION.SDK_INT >= 16) { 142 ActivityCompatJB.finishAffinity(activity); 143 } else { 144 activity.finish(); 145 } 146 } 147 148 /** 149 * Reverses the Activity Scene entry Transition and triggers the calling Activity 150 * to reverse its exit Transition. When the exit Transition completes, 151 * {@link Activity#finish()} is called. If no entry Transition was used, finish() is called 152 * immediately and the Activity exit Transition is run. 153 * 154 * <p>On Android 4.4 or lower, this method only finishes the Activity with no 155 * special exit transition.</p> 156 */ 157 public static void finishAfterTransition(Activity activity) { 158 if (Build.VERSION.SDK_INT >= 21) { 159 ActivityCompat21.finishAfterTransition(activity); 160 } else { 161 activity.finish(); 162 } 163 } 164 165 /** 166 * When {@link android.app.ActivityOptions#makeSceneTransitionAnimation(Activity, 167 * android.view.View, String)} was used to start an Activity, <var>callback</var> 168 * will be called to handle shared elements on the <i>launched</i> Activity. This requires 169 * {@link android.view.Window#FEATURE_CONTENT_TRANSITIONS}. 170 * 171 * @param callback Used to manipulate shared element transitions on the launched Activity. 172 */ 173 public static void setEnterSharedElementCallback(Activity activity, 174 SharedElementCallback callback) { 175 if (Build.VERSION.SDK_INT >= 21) { 176 ActivityCompat21.setEnterSharedElementCallback(activity, createCallback(callback)); 177 } 178 } 179 180 /** 181 * When {@link android.app.ActivityOptions#makeSceneTransitionAnimation(Activity, 182 * android.view.View, String)} was used to start an Activity, <var>callback</var> 183 * will be called to handle shared elements on the <i>launching</i> Activity. Most 184 * calls will only come when returning from the started Activity. 185 * This requires {@link android.view.Window#FEATURE_CONTENT_TRANSITIONS}. 186 * 187 * @param callback Used to manipulate shared element transitions on the launching Activity. 188 */ 189 public static void setExitSharedElementCallback(Activity activity, 190 SharedElementCallback callback) { 191 if (Build.VERSION.SDK_INT >= 21) { 192 ActivityCompat21.setExitSharedElementCallback(activity, createCallback(callback)); 193 } 194 } 195 196 public static void postponeEnterTransition(Activity activity) { 197 if (Build.VERSION.SDK_INT >= 21) { 198 ActivityCompat21.postponeEnterTransition(activity); 199 } 200 } 201 202 public static void startPostponedEnterTransition(Activity activity) { 203 if (Build.VERSION.SDK_INT >= 21) { 204 ActivityCompat21.startPostponedEnterTransition(activity); 205 } 206 } 207 208 private static ActivityCompat21.SharedElementCallback21 createCallback( 209 SharedElementCallback callback) { 210 ActivityCompat21.SharedElementCallback21 newCallback = null; 211 if (callback != null) { 212 newCallback = new ActivityCompat.SharedElementCallback21Impl(callback); 213 } 214 return newCallback; 215 } 216 217 private static class SharedElementCallback21Impl 218 extends ActivityCompat21.SharedElementCallback21 { 219 220 private SharedElementCallback mCallback; 221 222 public SharedElementCallback21Impl(SharedElementCallback callback) { 223 mCallback = callback; 224 } 225 226 @Override 227 public void onSharedElementStart(List<String> sharedElementNames, 228 List<View> sharedElements, List<View> sharedElementSnapshots) { 229 mCallback.onSharedElementStart(sharedElementNames, sharedElements, 230 sharedElementSnapshots); 231 } 232 233 @Override 234 public void onSharedElementEnd(List<String> sharedElementNames, List<View> sharedElements, 235 List<View> sharedElementSnapshots) { 236 mCallback.onSharedElementEnd(sharedElementNames, sharedElements, 237 sharedElementSnapshots); 238 } 239 240 @Override 241 public void onRejectSharedElements(List<View> rejectedSharedElements) { 242 mCallback.onRejectSharedElements(rejectedSharedElements); 243 } 244 245 @Override 246 public void onMapSharedElements(List<String> names, Map<String, View> sharedElements) { 247 mCallback.onMapSharedElements(names, sharedElements); 248 } 249 250 @Override 251 public Parcelable onCaptureSharedElementSnapshot(View sharedElement, 252 Matrix viewToGlobalMatrix, RectF screenBounds) { 253 return mCallback.onCaptureSharedElementSnapshot(sharedElement, viewToGlobalMatrix, 254 screenBounds); 255 } 256 257 @Override 258 public View onCreateSnapshotView(Context context, Parcelable snapshot) { 259 return mCallback.onCreateSnapshotView(context, snapshot); 260 } 261 } 262} 263