AnalyticalGraphicsInc/cesium — pull request #814 by mramato (2013-05-30 03:26:39+00:00)
Title: Widget API cleanup

As discussed in #781, while working on the CesiumViewerWidget replacement, I realized that our current API makes things a bit messy and confusing, it's also inconsistent with the non-widget API because of the use of public properties. Our documentation was also not very helpful in terms of knowing what was allowed to be modified or not. Finally, because we are using properties instead of functions, it makes it harder to aggregate domain objects, such as taking the scene in `CesiumWidget` and exposing it directly in the new `Viewer` widget.

So basically I cleaned up and streamlined everything with the following rules.

1. All public variables on ViewModel objects that are not observables or commands have been replaced with get/set functions. This basically includes sub-viewModels and "domain" objects, such as Scene.
2. Documentation for Observables start with either `Gets an Observable`, or `Gets a readonly Observable` so that end users can easily determine which is allowed.
3. Commands remain public properties (because they are really just functions), but their documentation is now more function-like.
4. For the Widgets themselves (not their view models), all public properties have been replaced with get/set methods.

Note, because the Timeline still needs an overhaul, I didn't do much there. Also, I didn't touch CesiumViewerWidget because it's going to go away very very soon (hopefully).

I'll also update our coding conventions to specifically discuss the widget layer and observables.