[Sub-object] Prototype sub-object selection

[VWoeltjen]

See #1101 for design. Implement sub-object selection at least to prototype quality; in particular, want to look at:

• What APIs need to be exposed? How should these be exposed?
• What is minimal functionality necessary for this to be validated with users? (See notes in [Sub-objects] Sub-object selection #1101, this has been discussed/scoped already)

[VWoeltjen]

Notes on scope & initial approach from discussion on 7/27/2016:

• Approach
  • Bring in new selection API
  • Use Selection from Inspector
  • Make tree Select and Navigate
  • Support Select from Plot

[VWoeltjen]

Think that Selection API from tutorial prototypes should be evolved here as well; we want the API to be flexible enough to support multi-select and selection context, whereas that API is rather minimal (single selection, no context)

[VWoeltjen]

Reference list of selection APIs, from web searching:

SketchUp
Unity
NetBeans
LibGDX
Eclipse

[VWoeltjen]

	Intuitive	Callbacky	Multiple	Context	Decoupled
SketchUp	✅	✅	✅	❌	❌
Unity	✅	✅	✅	Indirect	❌
NetBeans	❌	✅	❔	Indirect	✅
LibGDX	✅	✅	✅	❌	✅
Eclipse	❌	✅	✅	✅	✅

• "Intuitive" is subjective; NetBeans and Eclipse both have selection APIs
  which require lengthy documentation and refer to other APIs, so using
  these APIs seems like it would take more than just a quick skim through
  documentation. Other APIs are much more straightforward.
• "Callbacky" is just a fancy word for "fires change events." All the APIs
  here do so, and we were planning to do so, so that decision seems
  validated.
• "Multiple" refers to multi-select. We want an API that supports that
  while introducing minimal complexity to the simple case. It is unclear
  to me from NetBeans documentation whether or not this is supported.
  (Selections are modelled as "Lookups", which look powerful/effective
  but not very intuitive.)
• "Context" refers to the notion we have of a selection having some path.
  For instance, the "Remove" action would actually depend on the parent
  of the selection (so it needs to know that path.) In whiteboarding
  sessions, we've discussed handling this as an array and/or as a series
  of arguments to some method call. Only Eclipse includes this in the
  selection API (if I understand ITreeSelection.getPaths() correctly)
  and is then only one of several selection models. This is a bit of a
  red flag; should consider options to decouple selection from context.
  In some cases, there is an object hierarchy that can be accessed from
  the objects that get selected (which would be more similar to our
  getCapability('context') approach.)
• "Decoupled" is used to designate APIs which make minimal assumptions
  about what can be selected. APIs are considered decoupled if selections
  may be of arbitrary types, or if the type is non-arbitrary but can
  trivally wrap an arbitrary type.

SketchUp/LibGDX/Unity look like the models we want to follow; NetBeans/Eclipse have thoroughly-engineered selection models that look like they handle a broad range of cases well, but also impose a significant learning curve. We want to be simpler than an RCP.

The one thing we can't easily borrow from these is a solution for selection context. If this responsibility were moved to selected objects themselves, then this ceases to be a problem, but this also imposes restrictions on what can be selected.

[larkin]

I like looking at the other APIs for insights here. At the same time, I would ask: "What portion of 'selection' is part of the public API versus the private API?"

Publicly, I think developers need to be able to:

1. specify that nodes in their views are selectable
2. register views to show in the inspector in response to certain selections?
3. register views to show in the toolbar in response to certain selections?
4. register actions available for a given selection (which populate context menus)

Does this seem reasonable or is there a larger set of things we'd like them to do with selection? And is it okay to place a limit on the flexibility of our selection API?

On context, I'm thinking that ties into the first point above. We implement a method like MCT.makeSelectable(domElement, object) which adds selection functionality to a given domElement (css classes, gesture handlers, etc). To handle context, on selection, MCT climbs the tree to build the context path for the object, e.g. [object, parent, grandparent, ...]

For 2-4 if we stick with our initial concept of applying the context path to the canView function for a view or the canAct function for an action, we then allow view and action definitions to utilize context by accepting multiple arguments. The default behavior is "I don't care about context" but it's easy to opt in.

[VWoeltjen]

Very good point with the developer use cases - I was thinking naively of "plot uses selection" and going from there, but it is much nicer to say "plot says this legend entry is selectable" and let the platform handle it.

With the approach you describe, I think we can hide the selection API completely, particularly if toolbar and inspector are both views of the primary selection. The multi-select case complicates things somewhat; batching things works for at least some actions, but not for views. Treating views as views of a "composite domain object" could plausibly work, but things would get funny around indeterminate state. (Multi-select is out of scope for this issue, but don't want to move forward on a solution that will be incompatible.)

[larkin]

Hrm, the multi-select dillema again. Some experiments for methods of handling that:

// A) Keep current naming for singular selection, use new methods for multiple selection.
// checking for applicability (returns true/false)
canView = function (object, parent, grandparent) {};
canViewMultiple = function ([objectA, objectB], [parentA, parentB], [grandparentA, grandparentB]...) {};
// instantiating a view (returns view instance)
view = function (object, parent, grandparent...) {};
viewMultiple = function ([objectA, objectB], [parentA, parentB], [grandparentA, grandparentB]...) {};

// B) Overload existing functions and make it harder to register single views.
// check for applicability, return true/false
canView = function ([objectA, objectB], [parentA, parentB], [grandparentA, grandparentB]...) {};
// instantiating a view (returns view instance)
view = function ([objectA, objectB], [parentA, parentB], [grandparentA, grandparentB]...) {};

// C) perform view checking against singular selections multiple times, but define custom factory
// for rendering a view of multiple objects.  use inspection to determine if a view is valid for 
// multi selection: if all objects can be viewed, and the view defines a viewMultiple function, 
// then it will be used for the given selection
canView = function (object, parent, grandparent...) {}; 
// view factories return view instances.
view = function (object, parent, grandparent...) {};
viewMultiple = function ([objectA, objectB], [parentA, parentB], [grandparentA, grandparentB]...) {};

The same principles could work with Actions, but in the case of actions you don't necessarily need to implement different behavior to execute an action on a multiple selection, we could just batch them all in a transaction to ensure consistent pass/fail behavior. Though perhaps we could add functionality down the road to construct labels on demand, e.g. "remove" for a single item or "remove 2 items" with 2 items selected.

[larkin]

With regards to hiding the API completely: maybe we just put it in the background with a "provisional" flag, and expose functionality so that people generally don't need to use it. If we can find a way where no one needs to use it, then we remove it.

The uses cases I'm looking at to flesh out selection are visible in two places: the todo tutorial and the fixed position view. In these cases, The toolbar always has a "add" button, but it also gains a "delete" button when an object is selected.

Some questions for further thought-- do we layer selection on top of regions? i.e.

1. views or actions can be registered to the selection and will display in the inspector/toolbar/etc.
2. views registered to the toolbar or inspector region override default selection behavior.

[VWoeltjen]

Work in progress on branch subobject-selection-1126