| OLD | NEW |
| 1 Sky Widgets | 1 Sky Widgets |
| 2 =========== | 2 =========== |
| 3 | 3 |
| 4 Sky widgets are built using a functional-reactive framework, which takes | 4 Sky widgets are built using a functional-reactive framework, which takes |
| 5 inspiration from [React](http://facebook.github.io/react/). The central idea is | 5 inspiration from [React](http://facebook.github.io/react/). The central idea is |
| 6 that you build your UI out of components. Components describe what their view | 6 that you build your UI out of components. Components describe what their view |
| 7 should look like given their current configuration and state. When a component's | 7 should look like given their current configuration and state. When a component's |
| 8 state changes, the component rebuilds its description, which the framework diffs | 8 state changes, the component rebuilds its description, which the framework diffs |
| 9 against the previous description in order to determine the minial changes needed | 9 against the previous description in order to determine the minial changes needed |
| 10 in the underlying render tree to transition from one state to the next. | 10 in the underlying render tree to transition from one state to the next. |
| (...skipping 337 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 348 source of those values. | 348 source of those values. |
| 349 | 349 |
| 350 By convention, components typically store the values they receive from their | 350 By convention, components typically store the values they receive from their |
| 351 parents in public member variables and their own internal state in private | 351 parents in public member variables and their own internal state in private |
| 352 member variables. Therefore, a typical `syncFields` implementation will copy | 352 member variables. Therefore, a typical `syncFields` implementation will copy |
| 353 the public, but not the private, member variables from `source`. When | 353 the public, but not the private, member variables from `source`. When |
| 354 following this convention, there is no need to copy over the private member | 354 following this convention, there is no need to copy over the private member |
| 355 variables because those represent the internal state of the object and `this` | 355 variables because those represent the internal state of the object and `this` |
| 356 is the authoritative source of that state. | 356 is the authoritative source of that state. |
| 357 | 357 |
| 358 When implementing a `StatefulComponent`, make sure to call |
| 359 `super.syncFields(source)` from within your `syncFields()` method, |
| 360 unless you are extending `StatefulComponent` directly. |
| 361 |
| 358 Finally, when the user taps on the "Save" button, `MyDialog` follows the same | 362 Finally, when the user taps on the "Save" button, `MyDialog` follows the same |
| 359 pattern as `MyCheckbox` and calls a function passed in by its parent component | 363 pattern as `MyCheckbox` and calls a function passed in by its parent component |
| 360 to return the final value of the checkbox up the hierarchy. | 364 to return the final value of the checkbox up the hierarchy. |
| 361 | 365 |
| 362 didMount and didUnmount | 366 didMount and didUnmount |
| 363 ----------------------- | 367 ----------------------- |
| 364 | 368 |
| 365 When a component is inserted into the widget tree, the framework calls the | 369 When a component is inserted into the widget tree, the framework calls the |
| 366 `didMount` function on the component. When a component is removed from the | 370 `didMount` function on the component. When a component is removed from the |
| 367 widget tree, the framework calls the `didUnmount` function on the component. | 371 widget tree, the framework calls the `didUnmount` function on the component. |
| (...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 420 first entry in the previous build, even if, semantically, the first entry in | 424 first entry in the previous build, even if, semantically, the first entry in |
| 421 the list just scrolled off screen and is no longer visible in the viewport. | 425 the list just scrolled off screen and is no longer visible in the viewport. |
| 422 | 426 |
| 423 * By assigning each entry in the list a "semantic" key, the infinite list can | 427 * By assigning each entry in the list a "semantic" key, the infinite list can |
| 424 be more efficient because the framework will sync entries with matching | 428 be more efficient because the framework will sync entries with matching |
| 425 semantic keys and therefore similiar (or identical) visual appearances. | 429 semantic keys and therefore similiar (or identical) visual appearances. |
| 426 Moreover, syncing the entries semantically means that state retained in | 430 Moreover, syncing the entries semantically means that state retained in |
| 427 stateful subcomponents will remain attached to the same semantic entry rather | 431 stateful subcomponents will remain attached to the same semantic entry rather |
| 428 than the entry in the same numerical position in the viewport. | 432 than the entry in the same numerical position in the viewport. |
| 429 | 433 |
| 434 Useful debugging tools |
| 435 ---------------------- |
| 436 |
| 437 This is a quick way to dump the entire widget tree to the console. |
| 438 This can be quite useful in figuring out exactly what is going on when |
| 439 working with the widgets system. For this to work, you have to have |
| 440 launched your app with `runApp()`. |
| 441 |
| 442 ```dart |
| 443 import 'package:sky/widget/widget.dart'; |
| 444 |
| 445 debugDumpApp(); |
| 446 ``` |
| 447 |
| 430 Dependencies | 448 Dependencies |
| 431 ------------ | 449 ------------ |
| 432 | 450 |
| 433 * `package:vector_math` | 451 * `package:vector_math` |
| 434 * [`package:sky/animation`](../animation) | 452 * [`package:sky/animation`](../animation) |
| 435 * [`package:sky/base`](../base) | 453 * [`package:sky/base`](../base) |
| 436 * [`package:sky/painting`](../painting) | 454 * [`package:sky/painting`](../painting) |
| 437 * [`package:sky/rendering`](../rendering) | 455 * [`package:sky/rendering`](../rendering) |
| 438 * [`package:sky/theme`](../theme) | 456 * [`package:sky/theme`](../theme) |
| OLD | NEW |