From 28ce8ca8bd924eed34b3766bd693c7c2c26bfd32 Mon Sep 17 00:00:00 2001
From: Alexandre Bury <alexandre.bury@gmail.com>
Date: Thu, 21 Feb 2019 11:16:04 -0800
Subject: [PATCH] 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       | 10 ++++++++++
 src/view/finder.rs | 14 ++++++++++++--
 src/view/view.rs   | 22 ++++++++++++++++------
 3 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 34a1b7f..0578f32 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/src/view/finder.rs b/src/view/finder.rs
index 89f2e3f..eb1fac0 100644
--- a/src/view/finder.rs
+++ b/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 {
diff --git a/src/view/view.rs b/src/view/view.rs
index 3f8fb28..ff6f2aa 100644
--- a/src/view/view.rs
+++ b/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
-    /// to return one that fits the given `constraint`.
-    /// It's also fine to ignore it and return a fixed value.
+    /// Some views have a fixed size, and will ignore the `constraint`
+    /// parameter entirely.
+    ///
+    /// 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