1/*
2 * Copyright (C) 2015 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.app;
18
19import android.annotation.Nullable;
20import android.content.Context;
21import android.content.res.Configuration;
22import android.os.Bundle;
23import android.os.Parcelable;
24import android.util.ArrayMap;
25import android.util.AttributeSet;
26import android.view.Menu;
27import android.view.MenuInflater;
28import android.view.MenuItem;
29import android.view.View;
30
31import java.io.FileDescriptor;
32import java.io.PrintWriter;
33import java.util.List;
34
35/**
36 * Provides integration points with a {@link FragmentManager} for a fragment host.
37 * <p>
38 * It is the responsibility of the host to take care of the Fragment's lifecycle.
39 * The methods provided by {@link FragmentController} are for that purpose.
40 *
41 * @deprecated Use the <a href="{@docRoot}tools/extras/support-library.html">Support Library</a>
42 *      {@link android.support.v4.app.FragmentController}
43 */
44@Deprecated
45public class FragmentController {
46    private final FragmentHostCallback<?> mHost;
47
48    /**
49     * Returns a {@link FragmentController}.
50     */
51    public static final FragmentController createController(FragmentHostCallback<?> callbacks) {
52        return new FragmentController(callbacks);
53    }
54
55    private FragmentController(FragmentHostCallback<?> callbacks) {
56        mHost = callbacks;
57    }
58
59    /**
60     * Returns a {@link FragmentManager} for this controller.
61     */
62    public FragmentManager getFragmentManager() {
63        return mHost.getFragmentManagerImpl();
64    }
65
66    /**
67     * Returns a {@link LoaderManager}.
68     */
69    public LoaderManager getLoaderManager() {
70        return mHost.getLoaderManagerImpl();
71    }
72
73    /**
74     * Returns a fragment with the given identifier.
75     */
76    @Nullable
77    public Fragment findFragmentByWho(String who) {
78        return mHost.mFragmentManager.findFragmentByWho(who);
79    }
80
81    /**
82     * Attaches the host to the FragmentManager for this controller. The host must be
83     * attached before the FragmentManager can be used to manage Fragments.
84     * */
85    public void attachHost(Fragment parent) {
86        mHost.mFragmentManager.attachController(
87                mHost, mHost /*container*/, parent);
88    }
89
90    /**
91     * Instantiates a Fragment's view.
92     *
93     * @param parent The parent that the created view will be placed
94     * in; <em>note that this may be null</em>.
95     * @param name Tag name to be inflated.
96     * @param context The context the view is being created in.
97     * @param attrs Inflation attributes as specified in XML file.
98     *
99     * @return view the newly created view
100     */
101    public View onCreateView(View parent, String name, Context context, AttributeSet attrs) {
102        return mHost.mFragmentManager.onCreateView(parent, name, context, attrs);
103    }
104
105    /**
106     * Marks the fragment state as unsaved. This allows for "state loss" detection.
107     */
108    public void noteStateNotSaved() {
109        mHost.mFragmentManager.noteStateNotSaved();
110    }
111
112    /**
113     * Saves the state for all Fragments.
114     */
115    public Parcelable saveAllState() {
116        return mHost.mFragmentManager.saveAllState();
117    }
118
119    /**
120     * Restores the saved state for all Fragments. The given Fragment list are Fragment
121     * instances retained across configuration changes.
122     *
123     * @see #retainNonConfig()
124     *
125     * @deprecated use {@link #restoreAllState(Parcelable, FragmentManagerNonConfig)}
126     */
127    @Deprecated
128    public void restoreAllState(Parcelable state, List<Fragment> nonConfigList) {
129        mHost.mFragmentManager.restoreAllState(state,
130                new FragmentManagerNonConfig(nonConfigList, null));
131    }
132
133    /**
134     * Restores the saved state for all Fragments. The given FragmentManagerNonConfig are Fragment
135     * instances retained across configuration changes, including nested fragments
136     *
137     * @see #retainNestedNonConfig()
138     */
139    public void restoreAllState(Parcelable state, FragmentManagerNonConfig nonConfig) {
140        mHost.mFragmentManager.restoreAllState(state, nonConfig);
141    }
142
143    /**
144     * Returns a list of Fragments that have opted to retain their instance across
145     * configuration changes.
146     *
147     * @deprecated use {@link #retainNestedNonConfig()} to also track retained
148     *             nested child fragments
149     */
150    @Deprecated
151    public List<Fragment> retainNonConfig() {
152        return mHost.mFragmentManager.retainNonConfig().getFragments();
153    }
154
155    /**
156     * Returns a nested tree of Fragments that have opted to retain their instance across
157     * configuration changes.
158     */
159    public FragmentManagerNonConfig retainNestedNonConfig() {
160        return mHost.mFragmentManager.retainNonConfig();
161    }
162
163    /**
164     * Moves all Fragments managed by the controller's FragmentManager
165     * into the create state.
166     * <p>Call when Fragments should be created.
167     *
168     * @see Fragment#onCreate(Bundle)
169     */
170    public void dispatchCreate() {
171        mHost.mFragmentManager.dispatchCreate();
172    }
173
174    /**
175     * Moves all Fragments managed by the controller's FragmentManager
176     * into the activity created state.
177     * <p>Call when Fragments should be informed their host has been created.
178     *
179     * @see Fragment#onActivityCreated(Bundle)
180     */
181    public void dispatchActivityCreated() {
182        mHost.mFragmentManager.dispatchActivityCreated();
183    }
184
185    /**
186     * Moves all Fragments managed by the controller's FragmentManager
187     * into the start state.
188     * <p>Call when Fragments should be started.
189     *
190     * @see Fragment#onStart()
191     */
192    public void dispatchStart() {
193        mHost.mFragmentManager.dispatchStart();
194    }
195
196    /**
197     * Moves all Fragments managed by the controller's FragmentManager
198     * into the resume state.
199     * <p>Call when Fragments should be resumed.
200     *
201     * @see Fragment#onResume()
202     */
203    public void dispatchResume() {
204        mHost.mFragmentManager.dispatchResume();
205    }
206
207    /**
208     * Moves all Fragments managed by the controller's FragmentManager
209     * into the pause state.
210     * <p>Call when Fragments should be paused.
211     *
212     * @see Fragment#onPause()
213     */
214    public void dispatchPause() {
215        mHost.mFragmentManager.dispatchPause();
216    }
217
218    /**
219     * Moves all Fragments managed by the controller's FragmentManager
220     * into the stop state.
221     * <p>Call when Fragments should be stopped.
222     *
223     * @see Fragment#onStop()
224     */
225    public void dispatchStop() {
226        mHost.mFragmentManager.dispatchStop();
227    }
228
229    /**
230     * Moves all Fragments managed by the controller's FragmentManager
231     * into the destroy view state.
232     * <p>Call when the Fragment's views should be destroyed.
233     *
234     * @see Fragment#onDestroyView()
235     */
236    public void dispatchDestroyView() {
237        mHost.mFragmentManager.dispatchDestroyView();
238    }
239
240    /**
241     * Moves all Fragments managed by the controller's FragmentManager
242     * into the destroy state.
243     * <p>Call when Fragments should be destroyed.
244     *
245     * @see Fragment#onDestroy()
246     */
247    public void dispatchDestroy() {
248        mHost.mFragmentManager.dispatchDestroy();
249    }
250
251    /**
252     * Lets all Fragments managed by the controller's FragmentManager know the multi-window mode of
253     * the activity changed.
254     * <p>Call when the multi-window mode of the activity changed.
255     *
256     * @see Fragment#onMultiWindowModeChanged
257     * @deprecated use {@link #dispatchMultiWindowModeChanged(boolean, Configuration)}
258     */
259    @Deprecated
260    public void dispatchMultiWindowModeChanged(boolean isInMultiWindowMode) {
261        mHost.mFragmentManager.dispatchMultiWindowModeChanged(isInMultiWindowMode);
262    }
263
264    /**
265     * Lets all Fragments managed by the controller's FragmentManager know the multi-window mode of
266     * the activity changed.
267     * <p>Call when the multi-window mode of the activity changed.
268     *
269     * @see Fragment#onMultiWindowModeChanged
270     */
271    public void dispatchMultiWindowModeChanged(boolean isInMultiWindowMode,
272            Configuration newConfig) {
273        mHost.mFragmentManager.dispatchMultiWindowModeChanged(isInMultiWindowMode, newConfig);
274    }
275
276    /**
277     * Lets all Fragments managed by the controller's FragmentManager know the picture-in-picture
278     * mode of the activity changed.
279     * <p>Call when the picture-in-picture mode of the activity changed.
280     *
281     * @see Fragment#onPictureInPictureModeChanged
282     * @deprecated use {@link #dispatchPictureInPictureModeChanged(boolean, Configuration)}
283     */
284    @Deprecated
285    public void dispatchPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
286        mHost.mFragmentManager.dispatchPictureInPictureModeChanged(isInPictureInPictureMode);
287    }
288
289    /**
290     * Lets all Fragments managed by the controller's FragmentManager know the picture-in-picture
291     * mode of the activity changed.
292     * <p>Call when the picture-in-picture mode of the activity changed.
293     *
294     * @see Fragment#onPictureInPictureModeChanged
295     */
296    public void dispatchPictureInPictureModeChanged(boolean isInPictureInPictureMode,
297            Configuration newConfig) {
298        mHost.mFragmentManager.dispatchPictureInPictureModeChanged(isInPictureInPictureMode,
299                newConfig);
300    }
301
302    /**
303     * Lets all Fragments managed by the controller's FragmentManager
304     * know a configuration change occurred.
305     * <p>Call when there is a configuration change.
306     *
307     * @see Fragment#onConfigurationChanged(Configuration)
308     */
309    public void dispatchConfigurationChanged(Configuration newConfig) {
310        mHost.mFragmentManager.dispatchConfigurationChanged(newConfig);
311    }
312
313    /**
314     * Lets all Fragments managed by the controller's FragmentManager
315     * know the device is in a low memory condition.
316     * <p>Call when the device is low on memory and Fragment's should trim
317     * their memory usage.
318     *
319     * @see Fragment#onLowMemory()
320     */
321    public void dispatchLowMemory() {
322        mHost.mFragmentManager.dispatchLowMemory();
323    }
324
325    /**
326     * Lets all Fragments managed by the controller's FragmentManager
327     * know they should trim their memory usage.
328     * <p>Call when the Fragment can release allocated memory [such as if
329     * the Fragment is in the background].
330     *
331     * @see Fragment#onTrimMemory(int)
332     */
333    public void dispatchTrimMemory(int level) {
334        mHost.mFragmentManager.dispatchTrimMemory(level);
335    }
336
337    /**
338     * Lets all Fragments managed by the controller's FragmentManager
339     * know they should create an options menu.
340     * <p>Call when the Fragment should create an options menu.
341     *
342     * @return {@code true} if the options menu contains items to display
343     * @see Fragment#onCreateOptionsMenu(Menu, MenuInflater)
344     */
345    public boolean dispatchCreateOptionsMenu(Menu menu, MenuInflater inflater) {
346        return mHost.mFragmentManager.dispatchCreateOptionsMenu(menu, inflater);
347    }
348
349    /**
350     * Lets all Fragments managed by the controller's FragmentManager
351     * know they should prepare their options menu for display.
352     * <p>Call immediately before displaying the Fragment's options menu.
353     *
354     * @return {@code true} if the options menu contains items to display
355     * @see Fragment#onPrepareOptionsMenu(Menu)
356     */
357    public boolean dispatchPrepareOptionsMenu(Menu menu) {
358        return mHost.mFragmentManager.dispatchPrepareOptionsMenu(menu);
359    }
360
361    /**
362     * Sends an option item selection event to the Fragments managed by the
363     * controller's FragmentManager. Once the event has been consumed,
364     * no additional handling will be performed.
365     * <p>Call immediately after an options menu item has been selected
366     *
367     * @return {@code true} if the options menu selection event was consumed
368     * @see Fragment#onOptionsItemSelected(MenuItem)
369     */
370    public boolean dispatchOptionsItemSelected(MenuItem item) {
371        return mHost.mFragmentManager.dispatchOptionsItemSelected(item);
372    }
373
374    /**
375     * Sends a context item selection event to the Fragments managed by the
376     * controller's FragmentManager. Once the event has been consumed,
377     * no additional handling will be performed.
378     * <p>Call immediately after an options menu item has been selected
379     *
380     * @return {@code true} if the context menu selection event was consumed
381     * @see Fragment#onContextItemSelected(MenuItem)
382     */
383    public boolean dispatchContextItemSelected(MenuItem item) {
384        return mHost.mFragmentManager.dispatchContextItemSelected(item);
385    }
386
387    /**
388     * Lets all Fragments managed by the controller's FragmentManager
389     * know their options menu has closed.
390     * <p>Call immediately after closing the Fragment's options menu.
391     *
392     * @see Fragment#onOptionsMenuClosed(Menu)
393     */
394    public void dispatchOptionsMenuClosed(Menu menu) {
395        mHost.mFragmentManager.dispatchOptionsMenuClosed(menu);
396    }
397
398    /**
399     * Execute any pending actions for the Fragments managed by the
400     * controller's FragmentManager.
401     * <p>Call when queued actions can be performed [eg when the
402     * Fragment moves into a start or resume state].
403     * @return {@code true} if queued actions were performed
404     */
405    public boolean execPendingActions() {
406        return mHost.mFragmentManager.execPendingActions();
407    }
408
409    /**
410     * Starts the loaders.
411     */
412    public void doLoaderStart() {
413        mHost.doLoaderStart();
414    }
415
416    /**
417     * Stops the loaders, optionally retaining their state. This is useful for keeping the
418     * loader state across configuration changes.
419     *
420     * @param retain When {@code true}, the loaders aren't stopped, but, their instances
421     * are retained in a started state
422     */
423    public void doLoaderStop(boolean retain) {
424        mHost.doLoaderStop(retain);
425    }
426
427    /**
428     * Destroys the loaders and, if their state is not being retained, removes them.
429     */
430    public void doLoaderDestroy() {
431        mHost.doLoaderDestroy();
432    }
433
434    /**
435     * Lets the loaders know the host is ready to receive notifications.
436     */
437    public void reportLoaderStart() {
438        mHost.reportLoaderStart();
439    }
440
441    /**
442     * Returns a list of LoaderManagers that have opted to retain their instance across
443     * configuration changes.
444     */
445    public ArrayMap<String, LoaderManager> retainLoaderNonConfig() {
446        return mHost.retainLoaderNonConfig();
447    }
448
449    /**
450     * Restores the saved state for all LoaderManagers. The given LoaderManager list are
451     * LoaderManager instances retained across configuration changes.
452     *
453     * @see #retainLoaderNonConfig()
454     */
455    public void restoreLoaderNonConfig(ArrayMap<String, LoaderManager> loaderManagers) {
456        mHost.restoreLoaderNonConfig(loaderManagers);
457    }
458
459    /**
460     * Dumps the current state of the loaders.
461     */
462    public void dumpLoaders(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) {
463        mHost.dumpLoaders(prefix, fd, writer, args);
464    }
465}
466