1 /* 2 * Copyright (C) 2006 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 17 package android.os; 18 19 /** 20 * Interface for classes whose instances can be written to 21 * and restored from a {@link Parcel}. Classes implementing the Parcelable 22 * interface must also have a static field called <code>CREATOR</code>, which 23 * is an object implementing the {@link Parcelable.Creator Parcelable.Creator} 24 * interface. 25 * 26 * <p>A typical implementation of Parcelable is:</p> 27 * 28 * <pre> 29 * public class MyParcelable implements Parcelable { 30 * private int mData; 31 * 32 * public int describeContents() { 33 * return 0; 34 * } 35 * 36 * public void writeToParcel(Parcel out, int flags) { 37 * out.writeInt(mData); 38 * } 39 * 40 * public static final Parcelable.Creator<MyParcelable> CREATOR 41 * = new Parcelable.Creator<MyParcelable>() { 42 * public MyParcelable createFromParcel(Parcel in) { 43 * return new MyParcelable(in); 44 * } 45 * 46 * public MyParcelable[] newArray(int size) { 47 * return new MyParcelable[size]; 48 * } 49 * }; 50 * 51 * private MyParcelable(Parcel in) { 52 * mData = in.readInt(); 53 * } 54 * }</pre> 55 */ 56 public interface Parcelable { 57 /** 58 * Flag for use with {@link #writeToParcel}: the object being written 59 * is a return value, that is the result of a function such as 60 * "<code>Parcelable someFunction()</code>", 61 * "<code>void someFunction(out Parcelable)</code>", or 62 * "<code>void someFunction(inout Parcelable)</code>". Some implementations 63 * may want to release resources at this point. 64 */ 65 public static final int PARCELABLE_WRITE_RETURN_VALUE = 0x0001; 66 67 /** 68 * Bit masks for use with {@link #describeContents}: each bit represents a 69 * kind of object considered to have potential special significance when 70 * marshalled. 71 */ 72 public static final int CONTENTS_FILE_DESCRIPTOR = 0x0001; 73 74 /** 75 * Describe the kinds of special objects contained in this Parcelable's 76 * marshalled representation. 77 * 78 * @return a bitmask indicating the set of special object types marshalled 79 * by the Parcelable. 80 */ describeContents()81 public int describeContents(); 82 83 /** 84 * Flatten this object in to a Parcel. 85 * 86 * @param dest The Parcel in which the object should be written. 87 * @param flags Additional flags about how the object should be written. 88 * May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}. 89 */ writeToParcel(Parcel dest, int flags)90 public void writeToParcel(Parcel dest, int flags); 91 92 /** 93 * Interface that must be implemented and provided as a public CREATOR 94 * field that generates instances of your Parcelable class from a Parcel. 95 */ 96 public interface Creator<T> { 97 /** 98 * Create a new instance of the Parcelable class, instantiating it 99 * from the given Parcel whose data had previously been written by 100 * {@link Parcelable#writeToParcel Parcelable.writeToParcel()}. 101 * 102 * @param source The Parcel to read the object's data from. 103 * @return Returns a new instance of the Parcelable class. 104 */ createFromParcel(Parcel source)105 public T createFromParcel(Parcel source); 106 107 /** 108 * Create a new array of the Parcelable class. 109 * 110 * @param size Size of the array. 111 * @return Returns an array of the Parcelable class, with every entry 112 * initialized to null. 113 */ newArray(int size)114 public T[] newArray(int size); 115 } 116 117 /** 118 * Specialization of {@link Creator} that allows you to receive the 119 * ClassLoader the object is being created in. 120 */ 121 public interface ClassLoaderCreator<T> extends Creator<T> { 122 /** 123 * Create a new instance of the Parcelable class, instantiating it 124 * from the given Parcel whose data had previously been written by 125 * {@link Parcelable#writeToParcel Parcelable.writeToParcel()} and 126 * using the given ClassLoader. 127 * 128 * @param source The Parcel to read the object's data from. 129 * @param loader The ClassLoader that this object is being created in. 130 * @return Returns a new instance of the Parcelable class. 131 */ createFromParcel(Parcel source, ClassLoader loader)132 public T createFromParcel(Parcel source, ClassLoader loader); 133 } 134 } 135