AppCompatDelegate.java revision 3de8a4e8305507475d7890205184946a25cf45e7
1/* 2 * Copyright (C) 2014 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 androidx.appcompat.app; 18 19import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP; 20 21import android.app.Activity; 22import android.app.Dialog; 23import android.content.Context; 24import android.content.res.Configuration; 25import android.os.Build; 26import android.os.Bundle; 27import android.util.AttributeSet; 28import android.util.Log; 29import android.view.MenuInflater; 30import android.view.View; 31import android.view.ViewGroup; 32import android.view.Window; 33 34import androidx.annotation.IdRes; 35import androidx.annotation.IntDef; 36import androidx.annotation.LayoutRes; 37import androidx.annotation.NonNull; 38import androidx.annotation.Nullable; 39import androidx.annotation.RestrictTo; 40import androidx.appcompat.view.ActionMode; 41import androidx.appcompat.widget.Toolbar; 42import androidx.core.view.WindowCompat; 43import androidx.fragment.app.FragmentActivity; 44 45import java.lang.annotation.Retention; 46import java.lang.annotation.RetentionPolicy; 47 48/** 49 * This class represents a delegate which you can use to extend AppCompat's support to any 50 * {@link android.app.Activity}. 51 * 52 * <p>When using an {@link AppCompatDelegate}, you should call the following methods instead of the 53 * {@link android.app.Activity} method of the same name:</p> 54 * <ul> 55 * <li>{@link #addContentView(android.view.View, android.view.ViewGroup.LayoutParams)}</li> 56 * <li>{@link #setContentView(int)}</li> 57 * <li>{@link #setContentView(android.view.View)}</li> 58 * <li>{@link #setContentView(android.view.View, android.view.ViewGroup.LayoutParams)}</li> 59 * <li>{@link #requestWindowFeature(int)}</li> 60 * <li>{@link #hasWindowFeature(int)}</li> 61 * <li>{@link #invalidateOptionsMenu()}</li> 62 * <li>{@link #startSupportActionMode(androidx.appcompat.view.ActionMode.Callback)}</li> 63 * <li>{@link #setSupportActionBar(androidx.appcompat.widget.Toolbar)}</li> 64 * <li>{@link #getSupportActionBar()}</li> 65 * <li>{@link #getMenuInflater()}</li> 66 * <li>{@link #findViewById(int)}</li> 67 * </ul> 68 * 69 * <p>The following methods should be called from the {@link android.app.Activity} method of the 70 * same name:</p> 71 * <ul> 72 * <li>{@link #onCreate(android.os.Bundle)}</li> 73 * <li>{@link #onPostCreate(android.os.Bundle)}</li> 74 * <li>{@link #onConfigurationChanged(android.content.res.Configuration)}</li> 75 * <li>{@link #onStart()}</li> 76 * <li>{@link #onStop()}</li> 77 * <li>{@link #onPostResume()}</li> 78 * <li>{@link #onSaveInstanceState(Bundle)}</li> 79 * <li>{@link #setTitle(CharSequence)}</li> 80 * <li>{@link #onStop()}</li> 81 * <li>{@link #onDestroy()}</li> 82 * </ul> 83 * 84 * <p>An {@link Activity} can only be linked with one {@link AppCompatDelegate} instance, 85 * therefore the instance returned from {@link #create(Activity, AppCompatCallback)} should be 86 * retained until the Activity is destroyed.</p> 87 */ 88public abstract class AppCompatDelegate { 89 90 static final String TAG = "AppCompatDelegate"; 91 92 /** 93 * Mode which means to not use night mode, and therefore prefer {@code notnight} qualified 94 * resources where available, regardless of the time. 95 * 96 * @see #setLocalNightMode(int) 97 */ 98 public static final int MODE_NIGHT_NO = 1; 99 100 /** 101 * Mode which means to always use night mode, and therefore prefer {@code night} qualified 102 * resources where available, regardless of the time. 103 * 104 * @see #setLocalNightMode(int) 105 */ 106 public static final int MODE_NIGHT_YES = 2; 107 108 /** 109 * Mode which means to use night mode when it is determined that it is night or not. 110 * 111 * <p>The calculation used to determine whether it is night or not makes use of the location 112 * APIs (if this app has the necessary permissions). This allows us to generate accurate 113 * sunrise and sunset times. If this app does not have permission to access the location APIs 114 * then we use hardcoded times which will be less accurate.</p> 115 * 116 * @see #setLocalNightMode(int) 117 */ 118 public static final int MODE_NIGHT_AUTO = 0; 119 120 /** 121 * Mode which uses the system's night mode setting to determine if it is night or not. 122 * 123 * @see #setLocalNightMode(int) 124 */ 125 public static final int MODE_NIGHT_FOLLOW_SYSTEM = -1; 126 127 static final int MODE_NIGHT_UNSPECIFIED = -100; 128 129 @NightMode 130 private static int sDefaultNightMode = MODE_NIGHT_FOLLOW_SYSTEM; 131 132 private static boolean sCompatVectorFromResourcesEnabled = false; 133 134 /** @hide */ 135 @RestrictTo(LIBRARY_GROUP) 136 @IntDef({MODE_NIGHT_NO, MODE_NIGHT_YES, MODE_NIGHT_AUTO, MODE_NIGHT_FOLLOW_SYSTEM, 137 MODE_NIGHT_UNSPECIFIED}) 138 @Retention(RetentionPolicy.SOURCE) 139 public @interface NightMode {} 140 141 @IntDef({MODE_NIGHT_NO, MODE_NIGHT_YES, MODE_NIGHT_FOLLOW_SYSTEM}) 142 @Retention(RetentionPolicy.SOURCE) 143 @interface ApplyableNightMode {} 144 145 /** 146 * Flag for enabling the support Action Bar. 147 * 148 * <p>This is enabled by default for some devices. The Action Bar replaces the title bar and 149 * provides an alternate location for an on-screen menu button on some devices. 150 */ 151 public static final int FEATURE_SUPPORT_ACTION_BAR = 100 + WindowCompat.FEATURE_ACTION_BAR; 152 153 /** 154 * Flag for requesting an support Action Bar that overlays window content. 155 * Normally an Action Bar will sit in the space above window content, but if this 156 * feature is requested along with {@link #FEATURE_SUPPORT_ACTION_BAR} it will be layered over 157 * the window content itself. This is useful if you would like your app to have more control 158 * over how the Action Bar is displayed, such as letting application content scroll beneath 159 * an Action Bar with a transparent background or otherwise displaying a transparent/translucent 160 * Action Bar over application content. 161 * 162 * <p>This mode is especially useful with {@code View.SYSTEM_UI_FLAG_FULLSCREEN}, which allows 163 * you to seamlessly hide the action bar in conjunction with other screen decorations. 164 * When an ActionBar is in this mode it will adjust the insets provided to 165 * {@link View#fitSystemWindows(android.graphics.Rect) View.fitSystemWindows(Rect)} 166 * to include the content covered by the action bar, so you can do layout within 167 * that space. 168 */ 169 public static final int FEATURE_SUPPORT_ACTION_BAR_OVERLAY = 170 100 + WindowCompat.FEATURE_ACTION_BAR_OVERLAY; 171 172 /** 173 * Flag for specifying the behavior of action modes when an Action Bar is not present. 174 * If overlay is enabled, the action mode UI will be allowed to cover existing window content. 175 */ 176 public static final int FEATURE_ACTION_MODE_OVERLAY = WindowCompat.FEATURE_ACTION_MODE_OVERLAY; 177 178 /** 179 * Create a {@link androidx.appcompat.app.AppCompatDelegate} to use with {@code activity}. 180 * 181 * @param callback An optional callback for AppCompat specific events 182 */ 183 public static AppCompatDelegate create(Activity activity, AppCompatCallback callback) { 184 return create(activity, activity.getWindow(), callback); 185 } 186 187 /** 188 * Create a {@link androidx.appcompat.app.AppCompatDelegate} to use with {@code dialog}. 189 * 190 * @param callback An optional callback for AppCompat specific events 191 */ 192 public static AppCompatDelegate create(Dialog dialog, AppCompatCallback callback) { 193 return create(dialog.getContext(), dialog.getWindow(), callback); 194 } 195 196 private static AppCompatDelegate create(Context context, Window window, 197 AppCompatCallback callback) { 198 if (Build.VERSION.SDK_INT >= 24) { 199 return new AppCompatDelegateImplN(context, window, callback); 200 } else if (Build.VERSION.SDK_INT >= 23) { 201 return new AppCompatDelegateImplV23(context, window, callback); 202 } else { 203 return new AppCompatDelegateImplV14(context, window, callback); 204 } 205 } 206 207 /** 208 * Private constructor 209 */ 210 AppCompatDelegate() {} 211 212 /** 213 * Support library version of {@link Activity#getActionBar}. 214 * 215 * @return AppCompat's action bar, or null if it does not have one. 216 */ 217 @Nullable 218 public abstract ActionBar getSupportActionBar(); 219 220 /** 221 * Set a {@link Toolbar} to act as the {@link ActionBar} for this delegate. 222 * 223 * <p>When set to a non-null value the {@link #getSupportActionBar()} ()} method will return 224 * an {@link ActionBar} object that can be used to control the given toolbar as if it were 225 * a traditional window decor action bar. The toolbar's menu will be populated with the 226 * Activity's options menu and the navigation button will be wired through the standard 227 * {@link android.R.id#home home} menu select action.</p> 228 * 229 * <p>In order to use a Toolbar within the Activity's window content the application 230 * must not request the window feature 231 * {@link AppCompatDelegate#FEATURE_SUPPORT_ACTION_BAR FEATURE_SUPPORT_ACTION_BAR}.</p> 232 * 233 * @param toolbar Toolbar to set as the Activity's action bar, or {@code null} to clear it 234 */ 235 public abstract void setSupportActionBar(@Nullable Toolbar toolbar); 236 237 /** 238 * Return the value of this call from your {@link Activity#getMenuInflater()} 239 */ 240 public abstract MenuInflater getMenuInflater(); 241 242 /** 243 * Should be called from {@link Activity#onCreate Activity.onCreate()}. 244 * 245 * <p>This should be called before {@code super.onCreate()} as so:</p> 246 * <pre class="prettyprint"> 247 * protected void onCreate(Bundle savedInstanceState) { 248 * getDelegate().onCreate(savedInstanceState); 249 * super.onCreate(savedInstanceState); 250 * // ... 251 * } 252 * </pre> 253 */ 254 public abstract void onCreate(Bundle savedInstanceState); 255 256 /** 257 * Should be called from {@link Activity#onPostCreate(android.os.Bundle)} 258 */ 259 public abstract void onPostCreate(Bundle savedInstanceState); 260 261 /** 262 * Should be called from 263 * {@link Activity#onConfigurationChanged} 264 */ 265 public abstract void onConfigurationChanged(Configuration newConfig); 266 267 /** 268 * Should be called from {@link Activity#onStart()} Activity.onStart()} 269 */ 270 public abstract void onStart(); 271 272 /** 273 * Should be called from {@link Activity#onStop Activity.onStop()} 274 */ 275 public abstract void onStop(); 276 277 /** 278 * Should be called from {@link Activity#onPostResume()} 279 */ 280 public abstract void onPostResume(); 281 282 /** 283 * Finds a view that was identified by the id attribute from the XML that 284 * was processed in {@link #onCreate}. 285 * 286 * @return The view if found or null otherwise. 287 */ 288 @SuppressWarnings("TypeParameterUnusedInFormals") 289 @Nullable 290 public abstract <T extends View> T findViewById(@IdRes int id); 291 292 /** 293 * Should be called instead of {@link Activity#setContentView(android.view.View)}} 294 */ 295 public abstract void setContentView(View v); 296 297 /** 298 * Should be called instead of {@link Activity#setContentView(int)}} 299 */ 300 public abstract void setContentView(@LayoutRes int resId); 301 302 /** 303 * Should be called instead of 304 * {@link Activity#setContentView(android.view.View, android.view.ViewGroup.LayoutParams)}} 305 */ 306 public abstract void setContentView(View v, ViewGroup.LayoutParams lp); 307 308 /** 309 * Should be called instead of 310 * {@link Activity#addContentView(android.view.View, android.view.ViewGroup.LayoutParams)}} 311 */ 312 public abstract void addContentView(View v, ViewGroup.LayoutParams lp); 313 314 /** 315 * Should be called from {@link Activity#onTitleChanged(CharSequence, int)}} 316 */ 317 public abstract void setTitle(@Nullable CharSequence title); 318 319 /** 320 * Should be called from {@link Activity#invalidateOptionsMenu()}} or 321 * {@link FragmentActivity#supportInvalidateOptionsMenu()}. 322 */ 323 public abstract void invalidateOptionsMenu(); 324 325 /** 326 * Should be called from {@link Activity#onDestroy()} 327 */ 328 public abstract void onDestroy(); 329 330 /** 331 * Returns an {@link ActionBarDrawerToggle.Delegate} which can be returned from your Activity 332 * if it implements {@link ActionBarDrawerToggle.DelegateProvider}. 333 */ 334 @Nullable 335 public abstract ActionBarDrawerToggle.Delegate getDrawerToggleDelegate(); 336 337 /** 338 * Enable extended window features. This should be called instead of 339 * {@link android.app.Activity#requestWindowFeature(int)} or 340 * {@link android.view.Window#requestFeature getWindow().requestFeature()}. 341 * 342 * @param featureId The desired feature as defined in {@link android.view.Window}. 343 * @return Returns true if the requested feature is supported and now 344 * enabled. 345 */ 346 public abstract boolean requestWindowFeature(int featureId); 347 348 /** 349 * Query for the availability of a certain feature. 350 * 351 * <p>This should be called instead of {@link android.view.Window#hasFeature(int)}.</p> 352 * 353 * @param featureId The feature ID to check 354 * @return true if the feature is enabled, false otherwise. 355 */ 356 public abstract boolean hasWindowFeature(int featureId); 357 358 /** 359 * Start an action mode. 360 * 361 * @param callback Callback that will manage lifecycle events for this context mode 362 * @return The ContextMode that was started, or null if it was canceled 363 */ 364 @Nullable 365 public abstract ActionMode startSupportActionMode(@NonNull ActionMode.Callback callback); 366 367 /** 368 * Installs AppCompat's {@link android.view.LayoutInflater} Factory so that it can replace 369 * the framework widgets with compatible tinted versions. This should be called before 370 * {@code super.onCreate()} as so: 371 * <pre class="prettyprint"> 372 * protected void onCreate(Bundle savedInstanceState) { 373 * getDelegate().installViewFactory(); 374 * getDelegate().onCreate(savedInstanceState); 375 * super.onCreate(savedInstanceState); 376 * 377 * // ... 378 * } 379 * </pre> 380 * If you are using your own {@link android.view.LayoutInflater.Factory Factory} or 381 * {@link android.view.LayoutInflater.Factory2 Factory2} then you can omit this call, and instead call 382 * {@link #createView(android.view.View, String, android.content.Context, android.util.AttributeSet)} 383 * from your factory to return any compatible widgets. 384 */ 385 public abstract void installViewFactory(); 386 387 /** 388 * This should be called from a 389 * {@link android.view.LayoutInflater.Factory2 LayoutInflater.Factory2} in order 390 * to return tint-aware widgets. 391 * <p> 392 * This is only needed if you are using your own 393 * {@link android.view.LayoutInflater LayoutInflater} factory, and have therefore not 394 * installed the default factory via {@link #installViewFactory()}. 395 */ 396 public abstract View createView(@Nullable View parent, String name, @NonNull Context context, 397 @NonNull AttributeSet attrs); 398 399 /** 400 * Whether AppCompat handles any native action modes itself. 401 * <p>This methods only takes effect on 402 * {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH} and above. 403 * 404 * @param enabled whether AppCompat should handle native action modes. 405 */ 406 public abstract void setHandleNativeActionModesEnabled(boolean enabled); 407 408 /** 409 * Returns whether AppCompat handles any native action modes itself. 410 * 411 * @return true if AppCompat should handle native action modes. 412 */ 413 public abstract boolean isHandleNativeActionModesEnabled(); 414 415 /** 416 * Allows AppCompat to save instance state. 417 */ 418 public abstract void onSaveInstanceState(Bundle outState); 419 420 /** 421 * Allow AppCompat to apply the {@code night} and {@code notnight} resource qualifiers. 422 * 423 * <p>Doing this enables the 424 * {@link 425 * androidx.appcompat.R.style#Theme_AppCompat_DayNight Theme.AppCompat.DayNight} 426 * family of themes to work, using the computed twilight to automatically select a dark or 427 * light theme.</p> 428 * 429 * <p>You can override the night mode using {@link #setLocalNightMode(int)}.</p> 430 * 431 * <p>This only works on devices running 432 * {@link Build.VERSION_CODES#ICE_CREAM_SANDWICH ICE_CREAM_SANDWICH} and above.</p> 433 * 434 * <p>If this is called after the host component has been created, the component will either be 435 * automatically recreated or its {@link Configuration} updated. Which one depends on how 436 * the component is setup (via {@code android:configChanges} or similar).</p> 437 * 438 * @see #setDefaultNightMode(int) 439 * @see #setLocalNightMode(int) 440 * 441 * @return true if the night mode was applied, false if not 442 */ 443 public abstract boolean applyDayNight(); 444 445 /** 446 * Override the night mode used for this delegate's host component. This method only takes 447 * effect for those situations where {@link #applyDayNight()} works. 448 * 449 * <p>As this will call {@link #applyDayNight()}, the host component might be 450 * recreated automatically.</p> 451 */ 452 public abstract void setLocalNightMode(@NightMode int mode); 453 454 /** 455 * Sets the default night mode. This is used across all activities/dialogs but can be overridden 456 * locally via {@link #setLocalNightMode(int)}. 457 * 458 * <p>This method only takes effect for those situations where {@link #applyDayNight()} works. 459 * Defaults to {@link #MODE_NIGHT_NO}.</p> 460 * 461 * <p>This only takes effect for components which are created after the call. Any components 462 * which are already open will not be updated.</p> 463 * 464 * @see #setLocalNightMode(int) 465 * @see #getDefaultNightMode() 466 */ 467 public static void setDefaultNightMode(@NightMode int mode) { 468 switch (mode) { 469 case MODE_NIGHT_AUTO: 470 case MODE_NIGHT_NO: 471 case MODE_NIGHT_YES: 472 case MODE_NIGHT_FOLLOW_SYSTEM: 473 sDefaultNightMode = mode; 474 break; 475 default: 476 Log.d(TAG, "setDefaultNightMode() called with an unknown mode"); 477 break; 478 } 479 } 480 481 /** 482 * Returns the default night mode. 483 * 484 * @see #setDefaultNightMode(int) 485 */ 486 @NightMode 487 public static int getDefaultNightMode() { 488 return sDefaultNightMode; 489 } 490 491 /** 492 * Sets whether vector drawables on older platforms (< API 21) can be used within 493 * {@link android.graphics.drawable.DrawableContainer} resources. 494 * 495 * <p>When enabled, AppCompat can intercept some drawable inflation from the framework, which 496 * enables implicit inflation of vector drawables within 497 * {@link android.graphics.drawable.DrawableContainer} resources. You can then use those 498 * drawables in places such as {@code android:src} on {@link android.widget.ImageView}, 499 * or {@code android:drawableLeft} on {@link android.widget.TextView}. Example usage:</p> 500 * 501 * <pre> 502 * <selector xmlns:android="..."> 503 * <item android:state_checked="true" 504 * android:drawable="@drawable/vector_checked_icon" /> 505 * <item android:drawable="@drawable/vector_icon" /> 506 * </selector> 507 * 508 * <TextView 509 * ... 510 * android:drawableLeft="@drawable/vector_state_list_icon" /> 511 * </pre> 512 * 513 * <p>This feature defaults to disabled, since enabling it can cause issues with memory usage, 514 * and problems updating {@link Configuration} instances. If you update the configuration 515 * manually, then you probably do not want to enable this. You have been warned.</p> 516 * 517 * <p>Even with this disabled, you can still use vector resources through 518 * {@link androidx.appcompat.widget.AppCompatImageView#setImageResource(int)} and its 519 * {@code app:srcCompat} attribute. They can also be used in anything which AppCompat inflates 520 * for you, such as menu resources.</p> 521 * 522 * <p>Please note: this only takes effect in Activities created after this call.</p> 523 */ 524 public static void setCompatVectorFromResourcesEnabled(boolean enabled) { 525 sCompatVectorFromResourcesEnabled = enabled; 526 } 527 528 /** 529 * Returns whether vector drawables on older platforms (< API 21) can be accessed from within 530 * resources. 531 * 532 * @see #setCompatVectorFromResourcesEnabled(boolean) 533 */ 534 public static boolean isCompatVectorFromResourcesEnabled() { 535 return sCompatVectorFromResourcesEnabled; 536 } 537} 538