Skip to content

Commit 572646d

Browse files
committed
docs: cleanup
1 parent 36ac0ae commit 572646d

12 files changed

+404
-280
lines changed

content/guide/android-marshalling.md

+70-48
Large diffs are not rendered by default.

content/guide/data-binding.md

+36-23
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ There are various ways to manage data flow, often referred to as data bindings:
1919
```xml
2020
<Label text="{{ name }}" />
2121
```
22+
2223
```ts
2324
export class HelloWorldModel extends Observable {
2425
name = "John Doe"
@@ -27,14 +28,16 @@ export class HelloWorldModel extends Observable {
2728

2829
}
2930
```
31+
3032
- **One-way (to Model) data binding** - Binding which updates the model in relation to some action in the UI. The best example for this is a [tap](/guide/ui-components/gestures-in-nativescript#tap-gesture-in-nativescript) event.
3133

3234
```xml
3335
<Button text="Submit" tap="{{ onTap }}"/>
3436
```
37+
3538
```ts
3639
export class HelloWorldModel extends Observable {
37-
40+
3841
onTap(args: EventData){
3942

4043
}
@@ -49,6 +52,7 @@ export class HelloWorldModel extends Observable {
4952
```xml
5053
<TextField text="{{ name }}"/>
5154
```
55+
5256
```ts
5357
export class HelloWorldModel extends Observable {
5458
name = "John Doe"
@@ -60,12 +64,13 @@ export class HelloWorldModel extends Observable {
6064

6165
## Accessing parent bindingContext
6266

63-
A parent and a child UI components can have different binding contexts and the child component might need to bind its property to a source property in its parent's **bindingContext**.
67+
A parent and a child UI components can have different binding contexts and the child component might need to bind its property to a source property in its parent's **bindingContext**.
6468

6569
<!-- TODO: fix links -->
66-
Generally, the binding context is inheritable, but not when the components are created dynamically based on some data source. For example, [ListView]() creates its child items based on an `itemТemplate`, which describes what the ListView component will look like. When this component is added to the visual tree, for binding context it gets an element from a `ListView` items array (with the corresponding index).
6770

68-
This process creates a new binding context chain for the child item and its inner UI components. So, the inner UI component cannot access the binding context of the `ListView`. In order to solve this problem, NativeScript binding infrastructure has two special keywords:
71+
Generally, the binding context is inheritable, but not when the components are created dynamically based on some data source. For example, [ListView]() creates its child items based on an `itemТemplate`, which describes what the ListView component will look like. When this component is added to the visual tree, for binding context it gets an element from a `ListView` items array (with the corresponding index).
72+
73+
This process creates a new binding context chain for the child item and its inner UI components. So, the inner UI component cannot access the binding context of the `ListView`. In order to solve this problem, NativeScript binding infrastructure has two special keywords:
6974

7075
- `$parent` : denotes the binding context of the direct parent visual component
7176
- `$parents` : can be used as an array (with a number or string index). This gives you the option to choose either N levels of UI nesting or get a parent UI component with a given type.
@@ -85,22 +90,23 @@ NativeScript supports the following polymorphic binding expressions:
8590
### Property access
8691

8792
To access a value stored in an object property of the bindingContext, use the propert access expression:
88-
89-
```ts
90-
...
91-
user = {
92-
names:{
93-
first: "Sara"
94-
}
93+
94+
```ts
95+
...
96+
user = {
97+
names:{
98+
first: "Sara"
9599
}
96-
...
97-
```
100+
}
101+
...
102+
```
98103

99-
```xml
104+
```xml
100105

101106
<Label text="{{ user.name.first }}" textWrap="true" />
102107

103108
```
109+
104110
---
105111

106112
### array access
@@ -166,23 +172,29 @@ Supported operators: `>`,`<`, `<=`, `>=`, `==`, `!=`, `===`, `!==`.
166172
<Label text="{{ prop1 ? prop2 : prop3 }}" textWrap="true" />
167173

168174
```
175+
169176
---
177+
170178
### grouping parenthesis
171179

172180
```xml
173181

174182
<Label text="{{ prop1*(prop2 + prop3) }}" textWrap="true" />
175183

176184
```
185+
177186
---
187+
178188
### function calls
179189

180190
```xml
181191

182192
<Label text="{{ someMethod(p1,p2,...,pN) }}" textWrap="true" />
183193

184194
```
195+
185196
---
197+
186198
### comparison operators
187199

188200
```xml
@@ -194,6 +206,7 @@ Supported operators: `>`,`<`, `<=`, `>=`, `==`, `!=`, `===`, `!==`.
194206
Other supported operators are: `<`, `<=`, `>=`, `==`, `!=`, `===`, `!==`.
195207

196208
---
209+
197210
:::tip Note
198211
Special characters need to be escaped as follows:
199212

@@ -209,17 +222,17 @@ Often data within the Model is stored in a way that is optimized for best perfor
209222

210223
<!-- TODO: Add SB+Preview -->
211224

212-
```xml
225+
```xml
213226

214-
<StackLayout class="p-20 bg">
227+
<StackLayout class="p-20 bg">
215228

216-
<Label text="{{ date | dateConverter('dd-mm-yyyy') }}" textWrap="true" />
217-
<Label text="{{ name | toUpperCaseConverter }}" textWrap="true" />
218-
<Label text="{{ title | toTitle }}" textWrap="true" />
229+
<Label text="{{ date | dateConverter('dd-mm-yyyy') }}" textWrap="true" />
230+
<Label text="{{ name | toUpperCaseConverter }}" textWrap="true" />
231+
<Label text="{{ title | toTitle }}" textWrap="true" />
219232

220-
</StackLayout>
233+
</StackLayout>
221234

222-
```
235+
```
223236

224237
```ts
225238
export class HelloWorldModel extends Observable {
@@ -231,7 +244,7 @@ export class HelloWorldModel extends Observable {
231244
toUpperCaseConverter = this.toUpperCase()
232245
toTitle = this.convertToTitle()
233246

234-
...
247+
...
235248

236249
formatDate() {
237250
return {
@@ -274,4 +287,4 @@ Generally there is no need to stop binding explicitly since the Observable objec
274287

275288
```ts
276289
targetTextField.unbind('text')
277-
```
290+
```

content/guide/ios-marshalling.md

+18-16
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,9 @@ array.setObjectAtIndex(button, 1)
105105

106106
## Calling Objective-C/Swift methods with multiple arguments
107107

108-
Consider the following `NSMutableArray` selector: `replaceObjectsInRange:withObjectsFromArray:range:`.
109-
110-
In JavaScript it is represented by: `replaceObjectsInRangeWithObjectsFromArrayRange(objectsToRange, sourceArray, sourceRange)` (argument names are arbitrary).
108+
Consider the following `NSMutableArray` selector: `replaceObjectsInRange:withObjectsFromArray:range:`.
111109

110+
In JavaScript it is represented by: `replaceObjectsInRangeWithObjectsFromArrayRange(objectsToRange, sourceArray, sourceRange)` (argument names are arbitrary).
112111

113112
In Objective-C, when generating the function name for a method, it follows a convention of appending the names of the arguments defined by the Objective-C selector. The function name starts with a lowercase letter for the first argument and appends subsequent arguments with a capital letter.
114113

@@ -123,7 +122,8 @@ For an example of how to extend an Objective-C/Swift class, have a look at [Exte
123122
The below code shows how to convert a JavaScript array to a `CGFloat` array to pass it to an Objective-C method expecting `CGFloat` as an argument:
124123

125124
```js
126-
const CGFloatArray = interop.sizeof(interop.types.id) == 4 ? Float32Array : Float64Array
125+
const CGFloatArray =
126+
interop.sizeof(interop.types.id) == 4 ? Float32Array : Float64Array
127127
const jsArray = [4.5, 0, 1e-5, -1242e10, -4.5, 34, -34, -1e-6]
128128

129129
FloatArraySample.dumpFloats(CGFloatArray.from(jsArray), jsArray.length)
@@ -157,30 +157,31 @@ On the other hand, any API that expects a `NSNull`, `NSNumber`, `NSString` or `N
157157
### Converting numeric types
158158
159159
```ts
160-
console.log(`pow(2.5, 3) = ${Math.pow(2.5, 3)}`);
160+
console.log(`pow(2.5, 3) = ${Math.pow(2.5, 3)}`)
161161
```
162+
162163
The iOS Runtime converts JavaScript number literals to native doubles and utilizes the native pow(double x, double y) function. The resulting native integer is automatically converted back to a JavaScript number and then passed as an argument to console.log() for output..
163164

164165
### Converting string
166+
165167
```ts
166-
let button = UIButton.new();
167-
button.setTitleForState('Button title', UIControlState.Normal);
168-
console.log(button.titleLabel.text);
168+
let button = UIButton.new()
169+
button.setTitleForState('Button title', UIControlState.Normal)
170+
console.log(button.titleLabel.text)
169171
```
170172

171173
`Button title` is converted to `NSString` and the returned `NSString` is converted to JavaScript `string`.
172174

173175
### Converting boolean
174176

175177
```ts
176-
let str = NSString.stringWithString('YES');
177-
let isTrue = str.boolValue;
178+
let str = NSString.stringWithString('YES')
179+
let isTrue = str.boolValue
178180
```
179181

180182
## Objective-C Protocols
181183

182-
Protocols in Objective-C serve a similar purpose as interfaces in other programming languages. They define a blueprint or contract that specifies the members (methods, properties, etc.) that a class should implement. Protocols are exposed as empty objects in JavaScript. Protocols are usually only referenced when [subclassing](/guide/subclassing/extending-classes-and-conforming-protocols-ios) an Objective-C class or when checking whether an object or class conforms to a protocol.
183-
184+
Protocols in Objective-C serve a similar purpose as interfaces in other programming languages. They define a blueprint or contract that specifies the members (methods, properties, etc.) that a class should implement. Protocols are exposed as empty objects in JavaScript. Protocols are usually only referenced when [subclassing](/guide/subclassing/extending-classes-and-conforming-protocols-ios) an Objective-C class or when checking whether an object or class conforms to a protocol.
184185

185186
```objc
186187
BOOL isCopying = [NSArray conformsToProtocol:@protocol(NSCopying)];
@@ -189,6 +190,7 @@ BOOL isCopying = [NSArray conformsToProtocol:@protocol(NSCopying)];
189190
```js
190191
const isCopying = NSArray.conformsToProtocol(NSCopying)
191192
```
193+
192194
To implement Objective-C/Swift protocols in NativeScript, hava look at [Conforming to Objective-C/Swift protocols in NativeScript](/guide/subclassing/extending-classes-and-conforming-protocols-ios#conforming-to-objective-c-swift-protocols-in-nativescript)
193195

194196
## Objective-C Selectors
@@ -272,12 +274,12 @@ UIView *view = [[UIView alloc] initWithFrame:rect];
272274
const rect = {
273275
origin: {
274276
x: 0,
275-
y: 0
277+
y: 0,
276278
},
277279
size: {
278280
width: 100,
279-
height: 100
280-
}
281+
height: 100,
282+
},
281283
}
282284
const view = UIView.alloc().initWithFrame(rect)
283285
```
@@ -350,4 +352,4 @@ const exists = fileManager.fileExistsAtPathIsDirectory('/var/log', isDirectory)
350352
if (isDirectory.value) {
351353
console.log('The path is actually a directory')
352354
}
353-
```
355+
```

content/guide/ios-runtime-types.md

+10-13
Original file line numberDiff line numberDiff line change
@@ -4,43 +4,40 @@ title: iOS Runtime Types
44

55
NativeScript provides the `interop` module for working with native C types, pointers, pointer arithmetic and memory.
66

7-
87
<!-- TODO: Add examples -->
98

109
## Using interop
1110

1211
### Creating a pointer
1312

14-
The `Pointer` type allows you to represent a void*.
13+
The `Pointer` type allows you to represent a void\*.
1514

1615
#### Using the constructor
1716

1817
To create a new pointer with the given offset, use the constructor:
1918

2019
```ts
21-
const interop1 = new interop.Pointer(34)
20+
const interop1 = new interop.Pointer(34)
2221
```
2322

2423
#### Creating a pointer by adding an offset from an existing pointer
2524

26-
```ts
25+
```ts
2726
const interop2 = interop1.add(4)
28-
```
27+
```
2928

3029
#### Creating a pointer by removing an offset to an existing pointer
3130

32-
```ts
31+
```ts
3332
const interop3 = interop1.subtract(3)
34-
```
33+
```
3534

3635
## interop API
3736

3837
### Pointer.toNumber()
3938

4039
```ts
41-
4240
pointerInstance.toNumber()
43-
4441
```
4542

4643
Converts the value of a `Pointer` instance to a number.
@@ -78,6 +75,7 @@ Releases the memory of the specified unadopted pointer.
7875
interop.sizeof(type: any): number
7976

8077
```
78+
8179
Returns the size of the provided type. The `type` can be: a class constructor (of Objective-C interface), an instance (wrapper of Objective-C interface), struct constructor, struct instance, reference, protocol, function (for c function), fundamental types
8280

8381
---
@@ -118,7 +116,6 @@ Wraps an NSData instance in an ArrayBuffer.
118116

119117
---
120118

121-
122119
### new Reference(value)
123120

124121
Creates a new reference around a JavaScript `value`. The native representation of the type will be determined during the first time the Reference is used in an operation involving marshalling.
@@ -143,7 +140,6 @@ Creates a function reference that can be marshalled as a native function pointer
143140

144141
### interop types
145142

146-
147143
- "void": Type\<void\>
148144
- bool: Type\<boolean\>
149145
- int8: Type\<number\>
@@ -165,7 +161,7 @@ Creates a function reference that can be marshalled as a native function pointer
165161
- "class": Type\<any\>
166162
- selector: Type\<string\>
167163

168-
----
164+
---
169165

170166
### new StructType()
171167

@@ -180,11 +176,12 @@ Create a new instance of the struct and initialize it from the fields of the pro
180176
---
181177

182178
### equals
179+
183180
```ts
184181
someStructTypeIntastance.equals(left: T, right: T): boolean
185182

186183
```
187184

188185
Checks two structs for equality.
189186

190-
---
187+
---

content/guide/metadata.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,9 @@ Missing metadata entities could result in bugs at runtime. For example, if a nat
7575
- On Android they are located in `platforms/android/build-tools/buildMetadata.log`
7676

7777
For each global symbol that is discovered by the generator, there should be a line providing information whether it was included in the metadata or not, and which rules or what exception caused this. Examples:
78+
7879
<!-- TODO: An example of the following -->
80+
7981
- `verbose: Blacklisted kCFBuddhistCalendar from CoreFoundation.CFLocale (disabled by 'CoreFoundation*:*')` - when there are no whitelist rules a blacklisted symbol will show only the rule which disabled it
8082
- `verbose: Blacklisted NSString from Foundation.NSString` - when there is at least one whitelist rule, some blacklisted symbols will not specify a rule. This means that the symbol didn't match any of the whitelist rules.
8183
- `verbose: Blacklisted PHImageContentModeDefault from Photos.PhotosTypes (enabled by 'Photos.PhotosTypes:*', disabled by 'Photos.PhotosTypes:PHImageContentMode*')`, `verbose: Blacklisted String from java.lang (enabled by java.lang:*, disabled by java.lang:String)` - a blacklisted entry which matches both a whitelist rule and a blacklist rule will specify both.
@@ -131,4 +133,3 @@ if (android.os.Build.VERSION.SDK_INT >= 21) {
131133
## iOS Metadata
132134

133135
This is our own custom data format for listing the iOS APIs we are aware of and can handle. It stores the minimal required information and provides a small size and highly efficient read access. iOS supports type introspection to some extent but along with the C APIs embedded all the way in the native APIs we had to store a lot of extra information. The Metadata is pre-generated at compile time from the SDK header files and embedded in the app package (ipa).
134-

0 commit comments

Comments
 (0)