The `sky_tool start` command starts the dev server and uploads your app to the device, installing `SkyShell.apk` if needed.
The `--checked` flag triggers checked mode, in which types are checked, asserts are run, and
various [debugging features](https://github.com/domokit/sky_engine/blob/master/sky/packages/sky/lib/base/debug.dart) are enabled.
The `sky_tool logs` command logs errors and Dart `print()` output from the app, automatically limiting the output to just output from Sky Dart code and the Sky Engine C++ code (which
for historical reasons currently uses the tag `chromium`.)
To avoid confusion from old log messages, you may wish to call `sky_tool logs --clear` before calling
`sky_tool start`, to clear the log between runs.
Rapid Iteration
---------------
As an alternative to running `./packages/sky/sky_tool start` every time you make a change,
you might prefer to have the SkyShell reload your app automatically for you as you edit. To
do this, run the following command:
-`./packages/sky/sky_tool listen`
This is a long-running command -- just press `ctrl-c` when you want to stop listening for
changes to the file system and automatically reloading your app.
Currently `sky_tool listen` only works for Android, but iOS device and iOS simulator support
are coming soon.
Debugging
---------
Sky uses [Observatory](https://www.dartlang.org/tools/observatory/) for
debugging and profiling. While running your Sky app using `sky_tool`, you can
access Observatory by navigating your web browser to
[http://localhost:8181/](http://localhost:8181/).
Building a standalone APK
-------------------------
Although it is possible to build a standalone APK containing your application,
doing so right now is difficult. If you're feeling brave, you can see how we
The `MyCheckbox` component follows the pattern for stateless components. It
stores the values it receives in its constructor in `final` member variables,
which it then uses during its `build` function. Notice that when the user taps
on the checkbox, the checkbox itself doesn't use `value`. Instead, the checkbox
calls a function it received from its parent component. This pattern lets you
store state higher in the component hierarchy, which causes the state to persist
for longer periods of time. In the extreme, the state stored on the `App`
component persists for the lifetime of the application.
The `MyDialog` component is more complicated because it is a stateful component.
Let's walk through the differences in `MyDialog` caused by its being stateful:
*`MyDialog` extends StatefulComponent instead of Component.
*`MyDialog` has non-`final` member variables. Over the lifetime of the dialog,
we'll need to modify the values of these member variables, which means we
cannot mark them `final`.
*`MyDialog` has private member variables. By convention, components store
values they receive from their parent in public member variables and store
their own internal, transient state in private member variables. There's no
requirement to follow this convention, but we've found that it helps keep us
organized.
* Whenever `MyDialog` modifies its transient state, the dialog does so inside
a `setState` callback. Using `setState` is important because it marks the
component as dirty and schedules it to be rebuilt. If a component modifies
its transient state outside of a `setState` callback, the framework won't
know that the component has changed state and might not call the component's
`build` function, which means the user interface might not update to reflect
the changed state.
*`MyDialog` implements the `syncConstructorArguments` member function. To
understand `syncConstructorArguments`, we'll need to dive a bit deeper into
how the `build` function is used by the framework.
A component's `build` function returns a tree of widgets that represent a
"virtual" description of its appearance. The first time the framework calls
`build`, the framework walks this description and creates a "physical" tree
of `RenderObjects` that matches the description. When the framework calls
`build` again, the component still returns a fresh description of its
appearence, but this time the framework compares the new description with the
previous description and makes the minimal modifications to the underlying
`RenderObjects` to make them match the new description.
In this process, old stateless components are discarded and the new stateless
components created by the parent component are retained in the widget
hierchy. Old _stateful_ components, however, cannot simply be discarded
because they contain state that needs to be preserved. Instead, the old
stateful components are retained in the widget hierarchy and asked to
`syncConstructorArguments` with the new instance of the component created by
the parent in its `build` function.
Without `syncConstructorArguments`, the new values the parent component
passed to the `MyDialog` constructor in the parent's `build` function would
be lost because they would be stored only as member variables on the new
instance of the component, which is not retained in the component hiearchy.
Therefore, the `syncConstructorArguments` function in a component should
update `this` to account for the new values the parent passed to `source`
because `source` is the authorative source of those values.
By convention, components typically store the values they receive from their
parents in public member variables and their own internal state in private
member variables. Therefore, a typical `syncConstructorArguments`
implementation will copy the public, but not the private, member variables
from `source`. When following this convention, there is no need to copy over
the private member variables because those represent the internal state of
the object and `this` is the authoritative source of that state.
When implementing a `StatefulComponent`, make sure to call
`super.syncConstructorArguments(source)` from within your
`syncConstructorArguments()` method, unless you are extending
`StatefulComponent` directly.
Finally, when the user taps on the "Save" button, `MyDialog` follows the same
pattern as `MyCheckbox` and calls a function passed in by its parent component
to return the final value of the checkbox up the hierarchy.
didMount and didUnmount
-----------------------
When a component is inserted into the widget tree, the framework calls the
`didMount` function on the component. When a component is removed from the
widget tree, the framework calls the `didUnmount` function on the component.
In some situations, a component that has been unmounted might again be mounted.
For example, a stateful component might receive a pre-built component from its
parent (similar to `child` from the `MyButton` example above) that the stateful
component might incorporate, then not incorporate, and then later incorporate
again in the widget tree it builds, according to its changing state.
Typically, a stateful component will override `didMount` to initialize any
non-trivial internal state. Initializing internal state in `didMount` is more
efficient (and less error-prone) than initializing that state during the
component's constructor because parent executes the component's constructor each
time the parent rebuilds even though the framework mounts only the first
instance into the widget hierarchy. (Instead of mounting later instances, the
framework passes them to the original instance in `syncConstructorArguments` so
that the first instance of the component can incorporate the values passed by
the parent to the component's constructor.)
Components often override `didUnmount` to release resources or to cancel
subscriptions to event streams from outside the widget hierachy. When overriding
either `didMount` or `didUnmount`, a component should call its superclass's
`didMount` or `didUnmount` function.
initState
---------
The framework calls the `initState` function on stateful components before
building them. The default implementation of initState does nothing. If your
component requires non-trivial work to initialize its state, you should
override initState and do it there rather than doing it in the stateful
component's constructor. If the component doesn't need to be built (for
example, if it was constructed just to have its fields synchronized with
an existing stateful component) you'll avoid unnecessary work. Also, some
operations that involve interacting with the widget hierarchy cannot be
done in a component's constructor.
When overriding `initState`, a component should call its superclass's
`initState` function.
Keys
----
If a component requires fine-grained control over which widgets sync with each
other, the component can assign keys to the widgets it builds. Without keys, the
framework matches widgets in the current and previous build according to their
`runtimeType` and the order in which they appear. With keys, the framework
requires that the two widgets have the same `key` as well as the same
`runtimeType`.
Keys are most useful in components that build many instances of the same type of
widget. For example, consider an infinite list component that builds just enough
copies of a particular widget to fill its visible region:
* Without keys, the first entry in the current build would always sync with the
first entry in the previous build, even if, semantically, the first entry in
the list just scrolled off screen and is no longer visible in the viewport.
* By assigning each entry in the list a "semantic" key, the infinite list can
be more efficient because the framework will sync entries with matching
semantic keys and therefore similiar (or identical) visual appearances.
Moreover, syncing the entries semantically means that state retained in
stateful subcomponents will remain attached to the same semantic entry rather
than the entry in the same numerical position in the viewport.
Widgets for Applications
------------------------
There are some widgets that do not correspond to on-screen pixels but that are
nonetheless useful for building applications.
*`Theme`: Takes a [ThemeData](../theme/README.md) object in its `data` argument, to configure the Material Design theme of the rest of the application (as given in the `child` argument).
*`TaskDescription`: Takes a `label` that names the application for the purpose of the Android task switcher. The colour of the application as used in the system UI is taken from the current `Theme`.
*`Navigator`: Takes a single argument, which must be a long-lived instance of `NavigatorState`. This object choreographs how the application goes from screen to screen (e.g. from the main screen to a settings screen), as well as modal dialogs, drawer state, and anything else that responds to the system "back" button. By convention the `NavigatorState` object is a private member variable of the class that inherits from `App`, initialized in the `initState()` function. The `NavigatorState` constructor takes a list of `Route` objects, each of which takes a `name` argument giving a path to identify the window (e.g. "/" for the home screen, "/settings" for the settings screen, etc), and a `builder` argument that takes a method which itself takes a `navigator` argument and a `route` argument and returns a `Widget` representing that screen.
Putting this together, a basic application becomes:
```
dart
import 'package:sky/widgets.dart';
class DemoApp extends App {
NavigationState _state;
void initState() {
_state = new NavigationState([
new Route(
name: '/',
builder: (navigator, route) {
return new Center(child: new Text('Hello Slightly More Elaborate World'));
}
)
]);
super.initState();
}
Widget build() {
return new Theme(
data: new ThemeData(
brightness: ThemeBrightness.light
),
child: new TaskDescription(
label: 'Sky Demo',
child: new Navigator(_state)
)
);
}
}
void main() {
runApp(new DemoApp());
}
```
Useful debugging tools
----------------------
This is a quick way to dump the entire widget tree to the console.
This can be quite useful in figuring out exactly what is going on when
working with the widgets system. For this to work, you have to have
