|
| 1 | +# Enumeration Mapping File Documentation |
| 2 | + |
| 3 | +## Background |
| 4 | + |
| 5 | +In order to help with binding enumification (the process of converting groups |
| 6 | +of Java constant int fields into C# enums), a file can be created that defines |
| 7 | +a map between the fields and the enums to be created. |
| 8 | + |
| 9 | +There is a CSV format and an XML format of this file. In practice, users are |
| 10 | +guided to the XML format via our [documentation][0] and templates. The CSV format |
| 11 | +is mainly used internally for `Mono.Android.dll`, as it converts thousands of |
| 12 | +constants into hundreds of enums. |
| 13 | + |
| 14 | +## CSV Format |
| 15 | + |
| 16 | +The basic format since the beginning of Xamarin contains up to 6 fields: |
| 17 | + |
| 18 | +* **API Level** - This is generally only used by `Mono.Android.dll` to denote |
| 19 | + the Android level the constant was introduced in. For other uses this |
| 20 | + is generally `0`. |
| 21 | +* **Enum Type** - C# namespace and type of the enum to create. For example: |
| 22 | + `Android.Views.WindowProgress`. |
| 23 | +* **Enum Member** - C# name of the enum to create. For example: |
| 24 | + `Start` |
| 25 | +* **Enum Value** - The value of the enum. For example: `0`. |
| 26 | +* **JNI Signature** - The JNI signature of the Java constant to convert. For example: |
| 27 | + `android/view/Window.PROGRESS_START`. |
| 28 | +* **Flags** - If this field contains `flags` the enum will be created with the |
| 29 | + `[Flags]` attribute. (Any member will `flags` will make the whole enum `[Flags]`.) |
| 30 | + |
| 31 | +Full example: |
| 32 | +``` |
| 33 | +10,Android.Views.WindowProgress,Start,android/view/Window.PROGRESS_START,0,flags |
| 34 | +``` |
| 35 | + |
| 36 | +--- |
| 37 | +**NOTE** |
| 38 | + |
| 39 | +Our CSV files also allow comments using `//`. Lines beginning with this |
| 40 | +sequence are ignored. |
| 41 | + |
| 42 | +--- |
| 43 | + |
| 44 | +### Transient Mode |
| 45 | + |
| 46 | +By default, Java constants referenced in this format are kept. However the |
| 47 | +file can contain a line like this at any point: |
| 48 | +``` |
| 49 | +- ENTER TRANSIENT MODE - |
| 50 | +``` |
| 51 | + |
| 52 | +Any v1 constants referenced *AFTER* this line will be removed from the bindings. |
| 53 | +(This will not affect v2 constants.) |
| 54 | + |
| 55 | +## CSV Format v2 |
| 56 | + |
| 57 | +Over time we have found some limitations to the format, such as being able |
| 58 | +to specify if the Java constant field should be removed. Additionally, since the |
| 59 | +format only specifies constants that *SHOULD* be mapped, we cannot use this |
| 60 | +to track constants that we have examined and determined *SHOULD NOT* be mapped. |
| 61 | +This has led to various blacklists and tooling of varying success to prevent |
| 62 | +us from needing to continually re-audit those constants. |
| 63 | + |
| 64 | +There is now a "v2" version of defining constants. This is a line-level change |
| 65 | +and you can mix "v1" and "v2" lines in the same file for backwards compatibility, |
| 66 | +but for consistency it's probably better to stick to one style. |
| 67 | + |
| 68 | +A "v2" line contains up to 8 fields: |
| 69 | + |
| 70 | +* **Action** - The action to perform. This is what denotes a "v2" line, if the first |
| 71 | + character is not one of the following it will be treated as "v1". |
| 72 | + * `E` - Create a C# enum from a Java constant |
| 73 | + * `A` - Create a C# enum not mapped to a Java constant |
| 74 | + * `R` - Remove a Java constant but do not create a C# enum |
| 75 | + * `I` - Explicitly ignore this Java constant |
| 76 | + * `?` - Unknown, an explicit action has not been decided yet, will be ignored |
| 77 | +* **API Level** - This is generally only used by `Mono.Android.dll` to denote |
| 78 | + the Android level the constant was introduced in. For other uses this |
| 79 | + is generally `0`. |
| 80 | +* **JNI Signature** - The JNI signature of the Java constant to convert. For example: |
| 81 | + `android/view/Window.PROGRESS_START`. |
| 82 | +* **Enum Value** - The value of the enum. For example: `0`. |
| 83 | +* **Enum Type** - C# namespace and type of the enum to create. For example: |
| 84 | + `Android.Views.WindowProgress`. |
| 85 | +* **Enum Member** - C# name of the enum to create. For example: |
| 86 | + `Start` |
| 87 | +* **Field Action** - Action to take on the Java constant. (This replaces Transient mode.) |
| 88 | + * `remove` - Remove the Java constant |
| 89 | + * `keep` - Keeps the Java constant |
| 90 | +* **Flags** - If this field contains `flags` the enum will be created with the |
| 91 | + `[Flags]` attribute. (Any member will `flags` will make the whole enum `[Flags]`.) |
| 92 | + |
| 93 | +Full example: |
| 94 | +``` |
| 95 | +E,10,android/view/Window.PROGRESS_START,0,Android.Views.WindowProgress,Start,remove,flags |
| 96 | +``` |
| 97 | + |
| 98 | +[0]: https://docs.microsoft.com/en-us/xamarin/android/platform/binding-java-library/customizing-bindings/java-bindings-metadata#enumfieldsxml-and-enummethodsxml |
0 commit comments