Merge pull request google#8 from matthew-carroll/develop

Update README

README.md

@@ -2,6 +2,127 @@ Hover
 =====
 Hover is a floating menu implementation for Android.
 
+Goals
+-----
+The goals of Hover are to:
+
+1. Provide an easy-to-use, out-of-the-box floating menu implementation for Android developers, and
+
+1. Provide common tools for Android developers to create their own floating menu.
+
+Beta Notice
+-------
+Hover is still under heavy development. There is still a lot of code cleanup to do, so expect breaking API changes over time.
+
+That said, Hover should be in a usable state at this time.
+
+Demo Hover Menu
+---------------
+A demo app is included with the Hover repo. Here are some screenshots of the demo in action.
+
+<img src="https://raw.githubusercontent.com/matthew-carroll/hover/gh-pages/images/screenrecords/hover-demo-screenrecord.gif" width="270" /> ![Demo Hover Menu - Launching](https://raw.githubusercontent.com/matthew-carroll/hover/gh-pages/images/screenshots/hover-demo-homescreen.png) ![Demo Hover Menu - Launching](https://raw.githubusercontent.com/matthew-carroll/hover/gh-pages/images/screenshots/hover-demo-menu-intro.png) 
+
+![Demo Hover Menu - Launching](https://raw.githubusercontent.com/matthew-carroll/hover/gh-pages/images/screenshots/hover-demo-menu-theming.png) ![Demo Hover Menu - Launching](https://raw.githubusercontent.com/matthew-carroll/hover/gh-pages/images/screenshots/hover-demo-menu-menulist.png) ![Demo Hover Menu - Launching](https://raw.githubusercontent.com/matthew-carroll/hover/gh-pages/images/screenshots/hover-demo-menu-placeholder.png)
+
+Getting Started
+---------------
+### Subclass HoverMenuService
+To get started with Hover, create a subclass of `HoverMenuService` to host your Hover menu. The only method that you're required to override is `createHoverMenuAdapter()` which essentially returns the content of your Hover menu.
+
+```java
+public class MyHoverMenuService extends HoverMenuService {
+
+    @Override
+    protected HoverMenuAdapter createHoverMenuAdapter() {
+        // Create and configure your content for the HoverMenu.
+        return myHoverMenuAdapter;
+    }
+
+}
+```
+
+### Implement A HoverMenuAdapter
+A `HoverMenuAdapter` acts a lot like a standard Android `Adapter`. `HoverMenuAdapter`s provide a `View` for each tab that appears in your Hover menu. It also provides the corresponding `NavigatorContent` for each tab.
+
+```java
+public class MyHoverMenuAdapter extends BaseHoverMenuAdapter {
+
+    private List<String> mTabs;
+    private Map<String, NavigatorContent> mContentMap = new HashMap<>();
+
+    public MyHoverMenuAdapter() {
+        mTabs = Arrays.asList("first", "second");
+        mContentMap.put("first", /*...*/);
+        mContentMap.put("second, /*...*/);
+    }
+
+    @Override
+    public void getTabCount() {
+        return mTabs.size();
+    }
+    
+    @Override
+    public long getTabId(int position) {
+        return mTabs.get(position).hashCode();
+    }
+    
+    @Override
+    public View getTabView(int position) {
+        String tabName = mTabs.get(position);
+        if ("first".equals(tabName)) {
+            // Create and return the tab View for "first".
+        } else if ("second".equals(tabName)) {
+            // Create and return the tab View for "second".
+        }
+        // etc.
+    }
+    
+    @Override
+    public NavigatorContent getNavigatorContent(int position) {
+        String tabName = mTabs.get(position);
+        return mContentMap.get(tabName);
+    }
+
+}
+```
+
+### Working Directly With A HoverMenu
+If you want to create your own Hover menu `Service` from scratch, or if you want to experiment with a `HoverMenu` directly, you can instantiate one yourself. Use `HoverMenuBuilder` to configure a `HoverMenu` for your particular requirements.
+
+```java
+// Build a HoverMenu.
+HoverMenu hoverMenu = new HoverMenuBuilder(context)
+                        .displayWithinWindow()
+                        .useNavigator(myNavigator)
+                        .startAtLocation(savedLocationMemento)
+                        .useAdapter(adapter)
+                        .build();
+
+// When you're ready for your HoverMenu to appear on screen.
+hoverMenu.show();
+
+// When you want to remove your HoverMenu from the screen.
+hoverMenu.hide();
+
+// When you want to force your HoverMenu to expand fullscreen.
+hoverMenu.expandMenu();
+
+// When you want to force your HoverMenu to collapse to a draggable icon.
+hoverMenu.collapseMenu();
+
+// When you want to change the tabs and content in your HoverMenu.
+hoverMenu.setAdapter(otherAdapter);
+
+// When you want to save the display state of your HoverMenu.
+Parcelable displayState = hoverMenu.createDisplayStateMemento();
+
+// When you want to be notified when your HoverMenu is added to/removed from the display.
+hoverMenu.addOnVisibilityChangeListener(listener);
+
+// When you want to be notified when your HoverMenu expands or collapses.
+hoverMenu.addOnCollapseAndExpandListener(listener);
+```
+
 Download
 --------
 Hover is available through jCenter:

hover/src/main/java/io/mattcarroll/hover/NavigatorContent.java

@@ -1,13 +1,22 @@
 package io.mattcarroll.hover;
 
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.view.View;
 
 /**
  * Content to be displayed by a {@link Navigator}.
  */
 public interface NavigatorContent {
 
+    /**
+     * Returns the title to be displayed with this content.
+     *
+     * @return title to display with this content, or null to keep whatever title is already being displayed
+     */
+    @Nullable
+    CharSequence getTitle();
+
     /**
      * Returns the visual display of this content.
      *

hover/src/main/java/io/mattcarroll/hover/defaulthovermenu/ToolbarNavigatorView.java

@@ -70,8 +70,7 @@ public void pushContent(@NonNull NavigatorContent content) {
 
         // Push and display the new page.
         mContentStack.push(content);
-        mContentContainer.addView(content.getView(), mContentLayoutParams);
-        content.onShown(this);
+        showContent(content);
 
         updateToolbarBackButton();
     }
@@ -84,8 +83,7 @@ public boolean popContent() {
 
             // Add back the previous content (if there is any).
             if (!mContentStack.isEmpty()) {
-                mContentContainer.addView(mContentStack.peek().getView(), mContentLayoutParams);
-                mContentStack.peek().onShown(this);
+                showContent(mContentStack.peek());
             }
 
             updateToolbarBackButton();
@@ -113,6 +111,14 @@ public void clearContent() {
         removeCurrentContent();
     }
 
+    private void showContent(@NonNull NavigatorContent content) {
+        if (null != content.getTitle()) {
+            mToolbar.setTitle(content.getTitle());
+        }
+        mContentContainer.addView(content.getView(), mContentLayoutParams);
+        content.onShown(this);
+    }
+
     private void removeCurrentContent() {
         NavigatorContent visibleContent = mContentStack.pop();
         mContentContainer.removeView(visibleContent.getView());

hover/src/main/java/io/mattcarroll/hover/defaulthovermenu/menus/MenuListNavigatorContent.java

@@ -42,6 +42,12 @@ public void setEmptyView(@Nullable View emptyView) {
         mMenuListView.setEmptyView(emptyView);
     }
 
+    @Nullable
+    @Override
+    public CharSequence getTitle() {
+        return mMenu.getTitle();
+    }
+
     @NonNull
     @Override
     public View getView() {
@@ -51,8 +57,6 @@ public View getView() {
     @Override
     public void onShown(@NonNull Navigator navigator) {
         mNavigator = navigator;
-        Log.d(TAG, "Setting title: " + mMenu.getTitle());
-        mNavigator.setTitle(mMenu.getTitle());
     }
 
     @Override