Skip to content

[Mono.Android] Enumify API-37.0, API-37.0 is "Stable" #11151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jonpryor wants to merge 4 commits into
base: main
Choose a base branch
from
+873 −67
Open

[Mono.Android] Enumify API-37.0, API-37.0 is "Stable" #11151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54877b0
[Mono.Android] Enumify API-37.0, API-37.0 is "Stable"
jonpryor Apr 16, 2026
373b46a
[Mono.Android] Finish Mapping methods
jonpryor Apr 21, 2026
5e0e22a
[Mono.Android] Address Copilot comments
jonpryor Apr 21, 2026
993da33
Merge branch 'main' into dev/jonpryor/jonp-enumify-api-37
jonpryor Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 36 additions & 6 deletions Documentation/workflow/HowToAddNewApiLevel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -385,8 +385,8 @@ Using BindingStudio:

- Update `CURRENT_API_LEVEL` in MainForm.cs
- Choose `Tools` -> `Add API Level Constants`
- Fill in existing `map.csv`: `xamarin-android/src/Mono.Android/map.csv`
- Fill in new `api.xml`: ex: `xamarin-android/src/Mono.Android/obj/Debug/net6.0/android-32/mcw/api.xml`
- Fill in existing `map.csv`: `dotnet/android/src/Mono.Android/map.csv`
- Fill in new `api.xml`: ex: `dotnet/android/src/Mono.Android/obj/Debug/net6.0/android-32/mcw/api.xml`
- Choose `File` -> `Save`

This adds all the new possible constants from the API level to `map.csv`. They will be
Expand All @@ -404,7 +404,7 @@ Example:
Using BindingStudio:

- Choose `File` -> `Open Constant Map`
- Choose existing `map.csv`: `xamarin-android/src/Mono.Android/map.csv`
- Choose existing `map.csv`: `dotnet/android/src/Mono.Android/map.csv`

The left tree view will be populated with every type that has possible constants that require
a decision. Clicking a tree node will show the grid of all constants in the type. The ones
Expand Down Expand Up @@ -446,6 +446,16 @@ BindingStudio crashes.

The left tree view can be updated by saving and reopening the `map.csv` file.

Once `map.csv` has been updated, run the following command:

```sh
git grep '\.[A-Z][a-z]\.' src/Mono.Android/map.csv
```

This checks for any namespace-parts which are two letters long, the first letter is
upper-case, and the second letter is lower-case, e.g. `.Pm.`. These should be all
upper-case, e.g. `.PM.`.

### Extract methods that possibly need enums

Using BindingStudio:
Expand All @@ -471,7 +481,7 @@ Example:
Using BindingStudio:

- Choose `File` -> `Open Constant Map`
- Choose existing `map.csv`: `xamarin-android/src/Mono.Android/map.csv`
- Choose existing `map.csv`: `dotnet/android/src/Mono.Android/map.csv`
- Choose `File` -> `Open Method Map`
- Choose the new `.csv` created in the previous step.

Expand Down Expand Up @@ -518,7 +528,21 @@ There are 3 possible options for a method parameter/return type:
- If desired enum is found, clicking it will populate dropdown
- Click **Save**

Use `File` -> `Save` to save your work often!
Use `File` -> `Save` to save your work often! Note that this only updates the file designated by
the `csv` variable within `MainForm.FindAPILevelMethodsToolStripMenuItem_Click`.

Once this process is complete, use `Tools` -> `Export Final Method Map`, and create a *new*
`.csv` file, e.g. `new-methodmap.csv`.

Copy the contents of `new-methodmap.csv` and *append* to `src/Mono.Android/methodmap.csv`.

There may be redundant duplicate entries within `methodmap.csv`. Use the **uniq**(1)
Unix app to remove duplicate entries.

```sh
uniq < src/Mono.Android/methodmap.csv > m
Comment on lines +539 to +543
Copy link

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs suggest using uniq to remove duplicate entries from methodmap.csv, but uniq only removes adjacent duplicates. If duplicates aren't consecutive (likely after appending), this won't fully de-duplicate. Consider updating the instructions to use sort | uniq (or sort -u) if order isn't important, or clarify that the file must be sorted/grouped first.

Suggested change
There may be redundant duplicate entries within `methodmap.csv`. Use the **uniq**(1)
Unix app to remove duplicate entries.
```sh
uniq < src/Mono.Android/methodmap.csv > m
There may be redundant duplicate entries within `methodmap.csv`. Use the **sort**(1)
Unix app with `-u` to sort the file and remove duplicate entries.
```sh
sort -u src/Mono.Android/methodmap.csv > m

Copilot uses AI. Check for mistakes.
\mv m src/Mono.Android/methodmap.csv
```

### Turning `int` into `Color`

Expand Down Expand Up @@ -558,6 +582,12 @@ To map parameter types:
* `//attr/@name` the XML attribute to update. For return types, this is `type`.
* The value of the `<attr/>` is `Android.Graphics.Color`.

For API-37+, we're trying a "pattern-based" approach, wherein:

* method names which return `int` and end in `Color`
* method parameter names which start with `color` or end in `Color`

are automatically converted into `Android.Graphics.Color`.
Comment on lines +585 to +590
Copy link
Copy Markdown

@github-actions github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 💡 Documentation — This description doesn't fully match the metadata implementation:

  1. The metadata also converts fields (not just method returns/parameters)
  2. The metadata also adds Tint pattern matching (method returns ending in Tint, set* parameters starting with tint or ending in Tint)
  3. Parameter conversion only applies to set* methods, not all methods

Consider updating to reflect the full scope:

For API-37+, we're trying a "pattern-based" approach, wherein:

  * fields named `color` or ending in `Color` (type `int`)
  * method names which return `int` and end in `Color` or `Tint`
  * `set*` method parameter names which start with `color`/`tint` or end in `Color`/`Tint`

are automatically converted into `Android.Graphics.Color`.

Rule: Documentation accuracy


### Finishing the method map

Expand All @@ -569,7 +599,7 @@ Using BindingStudio:
- Choose `Tools` -> `Export Final Method Map`
- Choose a temporary file name
- Open the temporary file, copy the contents to the bottom of the official:
- xamarin-android/src/Mono.Android/methodmap.csv
- dotnet/android/src/Mono.Android/methodmap.csv

Congrats! Enumification is complete!

Expand Down
Loading