Rename Finder::find_id -> Finder::call_on_id and add proper find_id

The previous naming looked like a bad case of copy-pasta.

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Next version (0.11.0)
+
+### New features
+
+- Breaking change: `Finder::find_id()` is renamed to `call_on_id()`, and a proper
+  `find_id()` was added instead.
+- Add `StackView::remove_layer()`
+- Add `CircularFocus` view (and bring proper circular focus to dialogs)
+- Add `HideableView::is_visible()`
+
 ## 0.10.0
 
 ### New features

src/view/finder.rs

@@ -1,6 +1,6 @@
 use std::any::Any;
 use view::{View, ViewPath, ViewWrapper};
-use views::IdView;
+use views::{IdView, ViewRef};
 
 /// Provides `call_on<V: View>` to views.
 ///
@@ -20,13 +20,23 @@ pub trait Finder {
         F: FnOnce(&mut V) -> R;
 
     /// Convenient method to use `call_on` with a `view::Selector::Id`.
-    fn find_id<V, F, R>(&mut self, id: &str, callback: F) -> Option<R>
+    fn call_on_id<V, F, R>(&mut self, id: &str, callback: F) -> Option<R>
     where
         V: View + Any,
         F: FnOnce(&mut V) -> R,
     {
         self.call_on(&Selector::Id(id), callback)
     }
+
+    /// Convenient method to find a view wrapped in an [`IdView`].
+    ///
+    /// [`IdView`]: views/struct.IdView.html
+    fn find_id<V>(&mut self, id: &str) -> Option<ViewRef<V>>
+    where
+        V: View + Any,
+    {
+        self.call_on_id(id, IdView::<V>::get_mut)
+    }
 }
 
 impl<T: View> Finder for T {

src/view/view.rs

@@ -25,7 +25,8 @@ pub trait View: Any + AnyView {
     /// It is guaranteed to be the size available for the call to `draw()`.
     fn layout(&mut self, Vec2) {}
 
-    /// Returns `true` if the view content changed since last layout phase.
+    /// Should return `true` if the view content changed since the last call
+    /// to `layout()`.
     ///
     /// This is mostly an optimisation for views where the layout phase is
     /// expensive.
@@ -44,9 +45,11 @@ pub trait View: Any + AnyView {
     ///
     /// This is the main way a view communicate its size to its parent.
     ///
-    /// If the view is flexible (it has multiple size options), it can try
+    /// Some views have a fixed size, and will ignore the `constraint`
-    /// to return one that fits the given `constraint`.
+    /// parameter entirely.
-    /// It's also fine to ignore it and return a fixed value.
+    ///
+    /// Some views are flexible, and may adapt fully or partially to the
+    /// constraints.
     ///
     /// Default implementation always return `(1,1)`.
     fn required_size(&mut self, constraint: Vec2) -> Vec2 {
@@ -56,9 +59,14 @@ pub trait View: Any + AnyView {
 
     /// Called when an event is received (key press, mouse event, ...).
     ///
-    /// You can return an `EventResult`, with an optional callback to be run.
+    /// You can return an `EventResult`:
+    /// * `EventResult::Ignored` means the event was not processed and may be
+    ///    sent to another view.
+    /// * `EventResult::Consumed` means the event was consumed and should not
+    ///    be sent to any other view. It may in addition include a callback
+    ///    to be run.
     ///
-    /// Default implementation just ignores it.
+    /// The default implementation just ignores any event.
     fn on_event(&mut self, Event) -> EventResult {
         EventResult::Ignored
     }
@@ -72,6 +80,8 @@ pub trait View: Any + AnyView {
     ///
     /// If the selector doesn't find a match, the closure will not be run.
     ///
+    /// View groups should implement this to forward the call to each children.
+    ///
     /// Default implementation is a no-op.
     fn call_on_any<'a>(&mut self, _: &Selector, _: AnyCb<'a>) {
         // TODO: FnMut -> FnOnce once it works