0
# Android Platform
1

2
Comprehensive Android SDK type definitions with support for multiple API levels (17-29) and AndroidX libraries. Provides native Android object access, memory management, and NativeScript-specific integration.
3

4
## Capabilities
5

6
### Android API Entry Points
7

8
Multiple Android API level variants for different minimum SDK requirements.
9

10
```typescript { .api }
11
// Default entry point (API level 17)
12
/// <reference path="./node_modules/tns-platform-declarations/android.d.ts" />
13

14
// API level specific variants (13 levels supported)
15
/// <reference path="./node_modules/tns-platform-declarations/android-17.d.ts" />
16
/// <reference path="./node_modules/tns-platform-declarations/android-18.d.ts" />
17
/// <reference path="./node_modules/tns-platform-declarations/android-19.d.ts" />
18
/// <reference path="./node_modules/tns-platform-declarations/android-20.d.ts" />
19
/// <reference path="./node_modules/tns-platform-declarations/android-21.d.ts" />
20
/// <reference path="./node_modules/tns-platform-declarations/android-22.d.ts" />
21
/// <reference path="./node_modules/tns-platform-declarations/android-23.d.ts" />
22
/// <reference path="./node_modules/tns-platform-declarations/android-24.d.ts" />
23
/// <reference path="./node_modules/tns-platform-declarations/android-25.d.ts" />
24
/// <reference path="./node_modules/tns-platform-declarations/android-26.d.ts" />
25
/// <reference path="./node_modules/tns-platform-declarations/android-27.d.ts" />
26
/// <reference path="./node_modules/tns-platform-declarations/android-28.d.ts" />
27
/// <reference path="./node_modules/tns-platform-declarations/android-29.d.ts" />
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
// Use default API level 17
34
/// <reference path="./node_modules/tns-platform-declarations/android.d.ts" />
35

36
// Or specify higher API level for additional features
37
/// <reference path="./node_modules/tns-platform-declarations/android-24.d.ts" />
38

39
const permission = android.Manifest.permission.CAMERA;
40
```
41

42
### Core Android Functions
43

44
Essential utility functions for Android development and native object handling.
45

46
```typescript { .api }
47
/**
48
 * Convert a JavaScript number to Android float primitive
49
 * @param num - The number to convert
50
 * @returns Android float value
51
 */
52
declare function float(num: number): any;
53

54
/**
55
 * Convert a JavaScript number to Android long primitive  
56
 * @param num - The number to convert
57
 * @returns Android long value
58
 */
59
declare function long(num: number): any;
60

61
/**
62
 * Trigger garbage collection in JavaScript
63
 */
64
declare var gc: () => void;
65

66
/**
67
 * Release the reference to the wrapped native Java object
68
 * @param object - The Java object to release
69
 */
70
declare function __releaseNativeCounterpart(object: java.lang.Object): void;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
// Convert numbers to Android primitives
77
const androidFloat = float(3.14159);
78
const androidLong = long(1234567890);
79

80
// Create and manage Java objects
81
const javaString = new java.lang.String("Hello Android");
82
// ... use the object
83
__releaseNativeCounterpart(javaString); // Release when done
84

85
// Trigger garbage collection
86
gc();
87
```
88

89
### Native Array Support
90

91
Enhanced array constructor for creating typed native arrays.
92

93
```typescript { .api }
94
interface ArrayConstructor {
95
  /**
96
   * Create a typed native array
97
   * @param type - The type of array elements  
98
   * @param count - Number of elements
99
   * @returns Native array instance
100
   */
101
  create(type: any, count: number): any;
102
}
103

104
declare module native {
105
  export class Array<T> {
106
    constructor();
107
    /** Number of elements in the array */
108
    length: number;
109
    /** Array element access by index */
110
    [index: number]: T;
111
  }
112
}
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
// Create native arrays
119
const intArray = Array.create("int", 10);
120
const stringArray = Array.create(java.lang.String, 5);
121

122
// Use native array wrapper
123
const nativeArray = new native.Array<string>();
124
nativeArray[0] = "first item";
125
console.log(nativeArray.length);
126
```
127

128
### Android SDK API
129

130
Complete Android SDK type definitions providing access to all Android framework classes and constants.
131

132
```typescript { .api }
133
declare module android {
134
  export class Manifest extends java.lang.Object {
135
    public static class: java.lang.Class<android.Manifest>;
136
    public constructor();
137
  }
138
  
139
  export module Manifest {
140
    export class permission extends java.lang.Object {
141
      public static class: java.lang.Class<android.Manifest.permission>;
142
      // Core permissions
143
      public static ACCESS_COARSE_LOCATION: string;
144
      public static ACCESS_FINE_LOCATION: string;
145
      public static ACCESS_NETWORK_STATE: string;
146
      public static ACCESS_WIFI_STATE: string;
147
      public static BLUETOOTH: string;
148
      public static BLUETOOTH_ADMIN: string;
149
      public static CAMERA: string;
150
      public static CALL_PHONE: string;
151
      public static CHANGE_NETWORK_STATE: string;
152
      public static CHANGE_WIFI_STATE: string;
153
      public static INTERNET: string;
154
      public static READ_CONTACTS: string;
155
      public static READ_EXTERNAL_STORAGE: string;
156
      public static READ_PHONE_STATE: string;
157
      public static RECORD_AUDIO: string;
158
      public static VIBRATE: string;
159
      public static WAKE_LOCK: string;
160
      public static WRITE_EXTERNAL_STORAGE: string;
161
      // And many more Android permissions...
162
    }
163
  }
164
}
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
// Access Android permissions
171
const locationPermission = android.Manifest.permission.ACCESS_FINE_LOCATION;
172
const cameraPermission = android.Manifest.permission.CAMERA;
173
const internetPermission = android.Manifest.permission.INTERNET;
174

175
// Create Android manifest reference
176
const manifest = new android.Manifest();
177
```
178

179
### AndroidX Support Libraries
180

181
AndroidX library type definitions for modern Android development with comprehensive compatibility matrix.
182

183
```typescript { .api }
184
// AndroidX declarations are included automatically with each API level
185
// Available androidx versions: 17, 23, 26, 28, 29
186

187
declare module androidx {
188
  // AndroidX support library types are automatically included
189
  // Content varies by androidx version - see compatibility matrix below
190
}
191
```
192

193
**AndroidX Version Compatibility Matrix:**
194

195
| Android API Level | AndroidX Version | File Size | Key Components |
196
|-------------------|------------------|-----------|----------------|
197
| android-17.d.ts   | androidx-17.d.ts | ~15MB     | Basic support libraries, legacy compatibility |
198
| android-18.d.ts   | androidx-17.d.ts | ~15MB     | Same as API 17 |
199
| android-19.d.ts   | androidx-17.d.ts | ~15MB     | Same as API 17 |
200
| android-20.d.ts   | androidx-17.d.ts | ~15MB     | Same as API 17 |
201
| android-21.d.ts   | androidx-17.d.ts | ~15MB     | Same as API 17 |
202
| android-22.d.ts   | androidx-17.d.ts | ~15MB     | Same as API 17 |
203
| android-23.d.ts   | androidx-23.d.ts | ~22MB     | AppCompat, RecyclerView, CardView |
204
| android-24.d.ts   | androidx-23.d.ts | ~22MB     | Same as API 23 |
205
| android-25.d.ts   | androidx-23.d.ts | ~22MB     | Same as API 23 |
206
| android-26.d.ts   | androidx-26.d.ts | ~28MB     | Architecture Components, Room, ViewModel |
207
| android-27.d.ts   | androidx-26.d.ts | ~28MB     | Same as API 26 |
208
| android-28.d.ts   | androidx-28.d.ts | ~34MB     | Navigation, WorkManager, CameraX |
209
| android-29.d.ts   | androidx-29.d.ts | ~36MB     | Jetpack Compose (early), Biometric |
210
211
**Usage Examples:**
212

213
```typescript
214
// AndroidX types are available automatically based on API level
215
/// <reference path="./node_modules/tns-platform-declarations/android-28.d.ts" />
216

217
// API 28+ includes advanced AndroidX components
218
const workRequest = new androidx.work.OneTimeWorkRequest.Builder(MyWorker.class).build();
219
const navController = androidx.navigation.Navigation.findNavController(activity, R.id.nav_host_fragment);
220

221
// API 23+ includes basic AndroidX components  
222
const recyclerView = new androidx.recyclerview.widget.RecyclerView(context);
223
const cardView = new androidx.cardview.widget.CardView(context);
224

225
// All API levels include basic support
226
const appCompatActivity = new androidx.appcompat.app.AppCompatActivity();
227
```
228

229
## API Level Structure
230

231
Each Android API level entry point follows this structure:
232

233
```typescript
234
/// <reference path="./android/android-platform-{level}.d.ts" />
235
/// <reference path="./android/androidx-{version}.d.ts" />  
236
/// <reference path="./android/common.d.ts" />
237
```
238

239
Where:
240
- `android-platform-{level}.d.ts` contains the complete Android SDK for that API level
241
- `androidx-{version}.d.ts` contains AndroidX support library definitions  
242
- `common.d.ts` includes common declarations and NativeScript widgets
243

244
## Memory Management
245

246
Proper memory management is crucial when working with native Android objects:
247

248
```typescript
249
// Always release native objects when done
250
const javaObject = new java.lang.Object();
251
try {
252
  // Use the object...
253
} finally {
254
  __releaseNativeCounterpart(javaObject);
255
}
256

257
// Trigger garbage collection periodically
258
gc();
259
```
260

261
## Performance Notes
262

263
- **API Level Selection**: Choose the lowest API level that meets your requirements
264
- **Memory Usage**: Android platform declarations are memory-intensive  
265
- **Build Performance**: Use `skipLibCheck: true` for faster compilation
266
- **Object Lifecycle**: Always release native objects to prevent memory leaks